Skip to content

Commit 0cbb84e

Browse files
wesleyboarwesleyboar
authored
docs: better readme + add small docs (#182)
1 parent 37ea224 commit 0cbb84e

File tree

3 files changed

+228
-39
lines changed

3 files changed

+228
-39
lines changed

‎README.md

+158-39
Original file line numberDiff line numberDiff line change
@@ -1,63 +1,182 @@
1-
# TACC CMS Project
1+
# Core-CMS-Resources
22

3-
The project-specific CMS code for TACC WMA Workspace Websites.
3+
Project-specific code built into the [Core CMS] project
44

5-
To add resources for a new project:
5+
> **Note**
6+
> You need not clone this repository to work on a CMS project. You may work on it directly within [Core CMS] as a [Git submodule][Git Submodules].
67
7-
1. Clone `/example_cms`.
8-
2. Read `/_readme_cms`.
8+
> **Warning**
9+
> This repository is deprecated. Do **not** deploy these websites via this repository with [TACC/Core-CMS#v3.12.0](https://github.com/TACC/Core-CMS/releases/tag/v3.12.0) or greater. **Instead**, [migrate them to Core CMS Custom](#port-project).[^1]
910
10-
To build such a CMS project, use [TACC/Core-CMS](https://github.com/TACC/Core-CMS).
11+
[^1]: [Websites with custom templates will experience a major problem.](https://github.com/TACC/Core-CMS-Resources/pull/176#issuecomment-1603194690) Even though not all websites have such templates **and** there is a [tested solution](https://github.com/TACC/Core-CMS-Resources/pull/176#issuecomment-1603215969), website development benefits so much from migration, that every opportunity is taken to encourage it.
1112

12-
> **Warning**
13-
> Do **not** deploy these websites via this repository with [TACC/Core-CMS#v3.12.0](https://github.com/TACC/Core-CMS/releases/tag/v3.12.0) or greater. **Instead**, migrate them to [Core CMS Custom].[^1]
13+
## Table of Contents
14+
15+
- [Related Repositories](#related-repositories)
16+
- [Project Websites](#project-websites)
17+
- [Project Architecture](#project-architecture)
18+
- [Prerequisites](#prerequisites)
19+
- [Start Project](#start-project)
20+
- [Update Project](#update-project)
21+
- [Run Project](#run-project)
22+
- [Debug Project](#debug-project)
23+
- [Build & Deploy Project](#build--deploy-project)
24+
- [Port Project](#port-project)
1425

1526
## Related Repositories
1627

17-
- [Camino], a Docker container-based deployment scheme
1828
- [Core CMS], the base CMS code for TACC WMA CMS Websites
1929
- [Core CMS Custom], the custom CMS code (new solution) for TACC WMA CMS Websites
2030

31+
## Project Websites
32+
33+
| Abbr. | URL | Status
34+
| - | - | -
35+
| a2cps | https://a2cps.org/ | [migrating](https://github.com/TACC/Core-CMS-Custom/pull/175)
36+
| brainmap | https://portal.brainmap.org/
37+
| ecep | https://ecepalliance.org/ | [migrating](https://github.com/TACC/Core-CMS-Custom/pull/184)
38+
| epoc | https://prod.epoc.tacc.utexas.edu/
39+
| frontera | https://frontera-portal.tacc.utexas.edu/
40+
| lccf | https://lccf.tacc.utexas.edu/
41+
| 3dem | https://3dem.org/
42+
| protx | https://ccprotx.org/
43+
| sciviscolor | https://sciviscolor.org/
44+
| texascale | https://texascale.org/
45+
| utrc | https://utrc.tacc.utexas.edu/
46+
47+
## Project Architecture
48+
49+
Within a `/custom_project_dir` can be:
50+
51+
| directory | contents |
52+
| - | - |
53+
| `static` | static assets, organized as Django CMS expects |
54+
| `templates` | templates and saved snippets |
55+
| `settings_custom.py` | project-specific values for [Core CMS] settings |
56+
57+
## Prerequisites
58+
59+
- [Git Submodules]
60+
- [Core CMS]
61+
62+
A CMS project is run within [Core CMS]. Also, [Git Submodules] must be pre-installed on the system on which you will run the CMS project.
63+
64+
> **Note**
65+
> The [Core CMS] has its own prerequisites.
66+
67+
## Start Project
68+
69+
Set up a new local CMS instance.
70+
71+
0. Core CMS:
72+
73+
1. If not already done:
74+
1. Clone [Core CMS] repository.
75+
2. [Set up Core CMS](https://github.com/TACC/Core-CMS#readme) completely.
76+
2. Be in your [Core CMS] clone:
77+
78+
```sh
79+
cd Core-CMS
80+
```
81+
82+
3. Register and populate `/taccsite-custom`.
83+
84+
```sh
85+
git submodule init
86+
# This registers this repository at `/taccsite_custom`.
87+
git submodule update
88+
# This populates from this repository into `/taccsite_custom`.
89+
```
90+
91+
4. Create a symlink from `taccsite_cms/settings_custom.py` to `taccsite_custom/custom_project_dir/settings_custom.py`, e.g.
2192

22-
## Intended Usage
93+
```sh
94+
ln -s '../taccsite_custom/custom_project_dir/settings_custom.py' 'taccsite_cms/settings_custom.py'
95+
```
2396

24-
The Core CMS Resources is __not__ run independently.
97+
1. Docker Containers:
2598

26-
[Core CMS] loads assets from this repo.
99+
```sh
100+
docker exec -it core_cms /bin/bash
101+
# This opens a command prompt within the container.
102+
```
27103

28-
Please see the [Core CMS README].
104+
2. Django Application:
29105

106+
(Run these commands within the container.)
30107

31-
## Websites Maintained
108+
```sh
109+
python manage.py migrate
110+
# For projects that install apps
111+
# e.g. ECEP installs News/Blog
112+
npm ci
113+
npm run build --project="custom_project_dir"
114+
# If output includes
115+
# "Input Error: You must pass a valid"
116+
# then double check you have the directory
117+
# `taccsite_cms/…/static/…/css/src`
118+
python manage.py collectstatic --no-input
119+
```
32120

33-
- https://prod.a2cps.tacc.utexas.edu/ a.k.a. https://a2cps.org/<br />
34-
<sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/a2cps_cms/</sup>
35-
- https://prod.apcd.tacc.utexas.edu/ a.k.a. https://txapcd.org/<br />
36-
<sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/apcd_cms/</sup>
37-
- https://portal.brainmap.org/
38-
- https://democratizingdata.ai/<br />
39-
<sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/apcd_cms/</sup>
40-
- https://prod.ecep.tacc.utexas.edu/ a.k.a. https://ecepalliance.org/<br />
41-
<sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/ecep_cms/</sup>
42-
- https://prod.epoc.tacc.utexas.edu/
43-
- https://frontera-portal.tacc.utexas.edu/
44-
- https://lccf.tacc.utexas.edu/
45-
- https://3dem.org/
46-
- https://prod.protx.tacc.utexas.edu/
47-
- https://prod.sciviscolor.tacc.utexas.edu/
48-
- https://tapis-project.org/<br />
49-
<sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/tapisproject_cms/</sup>
50-
- https://texascale.org/
51-
- https://dev.tup.tacc.utexas.edu/<br />
52-
<sup>code has moved to https://github.com/TACC/tup-ui/blob/main/apps/tup-cms/</sup>
53-
- https://utrc.tacc.utexas.edu/
121+
3. Django CMS:
122+
1. Open http://localhost:8000/.
123+
2. Verify anything specific to the custom project is present e.g.
124+
- logo
125+
- custom applications
126+
- custom global colors
127+
- custom styles (may require specific markup)
128+
129+
> **Note**
130+
> A local machine CMS will be empty. It will **not** have content from staging nor production. To have that, follow and adapt instructions to [copy a database](https://confluence.tacc.utexas.edu/x/W4DZDg).
131+
132+
> **Note**
133+
> A local machine CMS does **not** include **nor** integrate with an instance of [Core Portal]. There are no reliable instructions to do either. **Help welcome.**
134+
135+
## Update Project
136+
137+
Update an existing local CMS instance.
138+
139+
1. If CMS `Dockerfile` changed, rebuild Docker Containers:
140+
141+
```sh
142+
make stop
143+
make build
144+
make start
145+
```
146+
147+
2. If static assets or database models changed, update the Django Application:
148+
149+
```sh
150+
docker exec -it core_cms /bin/bash
151+
# That opens a command prompt within the container.
152+
python manage.py migrate
153+
python manage.py collectstatic --no-input
154+
```
155+
156+
## Run Project
157+
158+
No developer instruction beyond those for Core CMS.
159+
160+
To run multiple projects, first read [Multiple Projects](./docs/run-project.md#multiple-projects).
161+
162+
## Debug Project
163+
164+
Read [Debug Project](./docs/debug-project.md) for miscellaneous tips.
165+
166+
## Build & Deploy Project
167+
168+
Follow "Core-CMS-Resources" section of [How To Build & Deploy][Build & Deploy Project].
169+
170+
## Port Project
171+
172+
To port a project to [Core CMS Custom], read [Port Project].
54173

55174
<!-- Link Aliases -->
56175

57176
[Core CMS]: https://github.com/TACC/Core-CMS
58-
[Core Styles]: https://github.com/TACC/Core-Styles
59177
[Core CMS Custom]: https://github.com/TACC/Core-CMS-Custom
60-
[Core CMS README]: https://github.com/TACC/Core-CMS/blob/main/README.md
61-
[Camino]: https://github.com/TACC/Camino
62178

63-
[^1]: [Websites with custom templates will experience a major problem.](https://github.com/TACC/Core-CMS-Resources/pull/176#issuecomment-1603194690) Even though not all websites have such templates **and** there is a [tested solution](https://github.com/TACC/Core-CMS-Resources/pull/176#issuecomment-1603215969), website development benefits so much from migration, that every opportunity is taken to encourage it.
179+
[Git Submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
180+
181+
[Build & Deploy Project]: https://confluence.tacc.utexas.edu/x/Lo99E
182+
[Port Project]: https://github.com/TACC/Core-CMS-Custom/blob/main/docs/port-project.md

‎docs/debug-project.md

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Debug Project
2+
3+
## Verify Images Are Collected
4+
5+
1. Review content of `/taccsite_custom/custom_project_dir/static/custom_project_dir/img`.
6+
2. Verify that content is also _in the container_ at `/static/custom_project_dir/img`.
7+
8+
## Verify CSS Build Output
9+
10+
1. Review content of `/taccsite_custom/custom_project_dir/static/custom_project_dir/css/build`.
11+
2. Verify that content is also _in the container_ at `/static/custom_project_dir/css/build`.

‎docs/run-project.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Run Project
2+
3+
## Individual Projects
4+
5+
No developer instruction beyond those for Core CMS.
6+
7+
## Multiple Projects
8+
9+
> **Note**
10+
> By default, multiple projects can not be run simultaneously.[^1]
11+
12+
To stop one project, and run another:
13+
14+
1. Cancel any active `make start` output i.e. press <kbd>control</kbd> + <kbd>C</kbd>.
15+
16+
2. Take down one project.
17+
18+
> **Note**
19+
> This is equivalent to deleting the relevant set of related containers in Docker Desktop.
20+
21+
```sh
22+
make stop
23+
```
24+
25+
3. Replace existing symlink.
26+
27+
Replace symlink `taccsite_cms/settings_custom.py` with one to `taccsite_custom/custom_project_dir/settings_custom.py`, e.g.
28+
29+
```sh
30+
rm -f 'taccsite_cms/settings_custom.py'
31+
ln -s '../taccsite_custom/custom_project_dir/settings_custom.py' 'taccsite_cms/settings_custom.py'
32+
```
33+
34+
4. Start the other project.
35+
36+
> **Note**
37+
> This retains containers and volumes e.g. database, search index.
38+
39+
> **Warning**
40+
> With these instructions, if a project has different apps installed, and especially if you used those apps on your local CMS, you will likely encounter an error. This document can **not** help you solve such an error.[^1]
41+
42+
```sh
43+
python manage.py migrate
44+
npm run build --project="custom_project_dir"
45+
python manage.py collectstatic --no-input
46+
```
47+
48+
[^1]: If you want to run multiple projects simultaneously, and avoid the Warning for multiple projects, see [Simultaneous Projects](#simultaneous-projects).
49+
50+
## Simultaneous Projects
51+
52+
> **Warning**
53+
> With these instructions, you will **not** be able to use the database (**nor** internal search index) of an already set up custom project (i.e. its local volumes).
54+
55+
To run multiple projects simultaneously:
56+
57+
1. Create another clone of [Core CMS].
58+
2. Set up the CMS in that clone.
59+
3. Set up the other project in that CMS.

0 commit comments

Comments
 (0)