docs: better readme + add small docs (#182)

TACC · Jul 18, 2023 · 0cbb84e · 0cbb84e
1 parent 37ea224
commit 0cbb84e
Show file tree

Hide file tree

Showing 3 changed files with 228 additions and 39 deletions.
diff --git a/README.md b/README.md
@@ -1,63 +1,182 @@
-# TACC CMS Project
+# Core-CMS-Resources
 
-The project-specific CMS code for TACC WMA Workspace Websites.
+Project-specific code built into the [Core CMS] project
 
-To add resources for a new project:
+> **Note**
+> 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].
 
-1. Clone `/example_cms`.
-2. Read `/_readme_cms`.
+> **Warning**
+> 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]
 
-To build such a CMS project, use [TACC/Core-CMS](https://github.com/TACC/Core-CMS).
+[^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.
 
-> **Warning**
-> 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]
+## Table of Contents
+
+- [Related Repositories](#related-repositories)
+- [Project Websites](#project-websites)
+- [Project Architecture](#project-architecture)
+- [Prerequisites](#prerequisites)
+- [Start Project](#start-project)
+- [Update Project](#update-project)
+- [Run Project](#run-project)
+- [Debug Project](#debug-project)
+- [Build & Deploy Project](#build--deploy-project)
+- [Port Project](#port-project)
 
 ## Related Repositories
 
-- [Camino], a Docker container-based deployment scheme
 - [Core CMS], the base CMS code for TACC WMA CMS Websites
 - [Core CMS Custom], the custom CMS code (new solution) for TACC WMA CMS Websites
 
+## Project Websites
+
+| Abbr. | URL | Status
+| - | - | -
+| a2cps | https://a2cps.org/ | [migrating](https://github.com/TACC/Core-CMS-Custom/pull/175)
+| brainmap | https://portal.brainmap.org/
+| ecep | https://ecepalliance.org/ | [migrating](https://github.com/TACC/Core-CMS-Custom/pull/184)
+| epoc | https://prod.epoc.tacc.utexas.edu/
+| frontera | https://frontera-portal.tacc.utexas.edu/
+| lccf | https://lccf.tacc.utexas.edu/
+| 3dem | https://3dem.org/
+| protx | https://ccprotx.org/
+| sciviscolor | https://sciviscolor.org/
+| texascale | https://texascale.org/
+| utrc | https://utrc.tacc.utexas.edu/
+
+## Project Architecture
+
+Within a `/custom_project_dir` can be:
+
+| directory | contents |
+| - | - |
+| `static` | static assets, organized as Django CMS expects |
+| `templates` | templates and saved snippets |
+| `settings_custom.py` | project-specific values for [Core CMS] settings |
+
+## Prerequisites
+
+- [Git Submodules]
+- [Core CMS]
+
+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.
+
+> **Note**
+> The [Core CMS] has its own prerequisites.
+
+## Start Project
+
+Set up a new local CMS instance.
+
+0. Core CMS:
+
+    1. If not already done:
+        1. Clone [Core CMS] repository.
+        2. [Set up Core CMS](https://github.com/TACC/Core-CMS#readme) completely.
+    2. Be in your [Core CMS] clone:
+
+        ```sh
+        cd Core-CMS
+        ```
+
+    3. Register and populate `/taccsite-custom`.
+
+        ```sh
+        git submodule init
+        # This registers this repository at `/taccsite_custom`.
+        git submodule update
+        # This populates from this repository into `/taccsite_custom`.
+        ```
+
+    4. Create a symlink from `taccsite_cms/settings_custom.py` to `taccsite_custom/custom_project_dir/settings_custom.py`, e.g.
 
-## Intended Usage
+        ```sh
+        ln -s '../taccsite_custom/custom_project_dir/settings_custom.py' 'taccsite_cms/settings_custom.py'
+        ```
 
-The Core CMS Resources is __not__ run independently.
+1. Docker Containers:
 
-[Core CMS] loads assets from this repo.
+    ```sh
+    docker exec -it core_cms /bin/bash
+    # This opens a command prompt within the container.
+    ```
 
-Please see the [Core CMS README].
+2. Django Application:
 
+    (Run these commands within the container.)
 
-## Websites Maintained
+    ```sh
+    python manage.py migrate
+    # For projects that install apps
+    # e.g. ECEP installs News/Blog
+    npm ci
+    npm run build --project="custom_project_dir"
+    # If output includes
+    # "Input Error: You must pass a valid"
+    # then double check you have the directory
+    # `taccsite_cms/…/static/…/css/src`
+    python manage.py collectstatic --no-input
+    ```
 
-- https://prod.a2cps.tacc.utexas.edu/ a.k.a. https://a2cps.org/<br />
-  <sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/a2cps_cms/</sup>
-- https://prod.apcd.tacc.utexas.edu/ a.k.a. https://txapcd.org/<br />
-  <sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/apcd_cms/</sup>
-- https://portal.brainmap.org/
-- https://democratizingdata.ai/<br />
-  <sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/apcd_cms/</sup>
-- https://prod.ecep.tacc.utexas.edu/ a.k.a. https://ecepalliance.org/<br />
-  <sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/ecep_cms/</sup>
-- https://prod.epoc.tacc.utexas.edu/
-- https://frontera-portal.tacc.utexas.edu/
-- https://lccf.tacc.utexas.edu/
-- https://3dem.org/
-- https://prod.protx.tacc.utexas.edu/
-- https://prod.sciviscolor.tacc.utexas.edu/
-- https://tapis-project.org/<br />
-  <sup>code has moved to https://github.com/TACC/Core-CMS-Custom/blob/main/tapisproject_cms/</sup>
-- https://texascale.org/
-- https://dev.tup.tacc.utexas.edu/<br />
-  <sup>code has moved to https://github.com/TACC/tup-ui/blob/main/apps/tup-cms/</sup>
-- https://utrc.tacc.utexas.edu/
+3. Django CMS:
+    1. Open http://localhost:8000/.
+    2. Verify anything specific to the custom project is present e.g.
+        - logo
+        - custom applications
+        - custom global colors
+        - custom styles (may require specific markup)
+
+> **Note**
+> 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).
+
+> **Note**
+> 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.**
+
+## Update Project
+
+Update an existing local CMS instance.
+
+1. If CMS `Dockerfile` changed, rebuild Docker Containers:
+
+    ```sh
+    make stop
+    make build
+    make start
+    ```
+
+2. If static assets or database models changed, update the Django Application:
+
+    ```sh
+    docker exec -it core_cms /bin/bash
+    # That opens a command prompt within the container.
+        python manage.py migrate
+        python manage.py collectstatic --no-input
+    ```
+
+## Run Project
+
+No developer instruction beyond those for Core CMS.
+
+To run multiple projects, first read [Multiple Projects](./docs/run-project.md#multiple-projects).
+
+## Debug Project
+
+Read [Debug Project](./docs/debug-project.md) for miscellaneous tips.
+
+## Build & Deploy Project
+
+Follow "Core-CMS-Resources" section of [How To Build & Deploy][Build & Deploy Project].
+
+## Port Project
+
+To port a project to [Core CMS Custom], read [Port Project].
 
 <!-- Link Aliases -->
 
 [Core CMS]: https://github.com/TACC/Core-CMS
-[Core Styles]: https://github.com/TACC/Core-Styles
 [Core CMS Custom]: https://github.com/TACC/Core-CMS-Custom
-[Core CMS README]: https://github.com/TACC/Core-CMS/blob/main/README.md
-[Camino]: https://github.com/TACC/Camino
 
-[^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.
+[Git Submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules
+
+[Build & Deploy Project]: https://confluence.tacc.utexas.edu/x/Lo99E
+[Port Project]: https://github.com/TACC/Core-CMS-Custom/blob/main/docs/port-project.md
diff --git a/docs/debug-project.md b/docs/debug-project.md
@@ -0,0 +1,11 @@
+# Debug Project
+
+## Verify Images Are Collected
+
+1. Review content of `/taccsite_custom/custom_project_dir/static/custom_project_dir/img`.
+2. Verify that content is also _in the container_ at `/static/custom_project_dir/img`.
+
+## Verify CSS Build Output
+
+1. Review content of `/taccsite_custom/custom_project_dir/static/custom_project_dir/css/build`.
+2. Verify that content is also _in the container_ at `/static/custom_project_dir/css/build`.
diff --git a/docs/run-project.md b/docs/run-project.md
@@ -0,0 +1,59 @@
+# Run Project
+
+## Individual Projects
+
+No developer instruction beyond those for Core CMS.
+
+## Multiple Projects
+
+> **Note**
+> By default, multiple projects can not be run simultaneously.[^1]
+
+To stop one project, and run another:
+
+1. Cancel any active `make start` output i.e. press <kbd>control</kbd> + <kbd>C</kbd>.
+
+2. Take down one project.
+
+    > **Note**
+    > This is equivalent to deleting the relevant set of related containers in Docker Desktop.
+
+    ```sh
+    make stop
+    ```
+
+3. Replace existing symlink.
+
+    Replace symlink `taccsite_cms/settings_custom.py` with one to `taccsite_custom/custom_project_dir/settings_custom.py`, e.g.
+
+    ```sh
+    rm -f 'taccsite_cms/settings_custom.py'
+    ln -s '../taccsite_custom/custom_project_dir/settings_custom.py' 'taccsite_cms/settings_custom.py'
+    ```
+
+4. Start the other project.
+
+    > **Note**
+    > This retains containers and volumes e.g. database, search index.
+
+    > **Warning**
+    > 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]
+
+    ```sh
+    python manage.py migrate
+    npm run build --project="custom_project_dir"
+    python manage.py collectstatic --no-input
+    ```
+
+[^1]: If you want to run multiple projects simultaneously, and avoid the Warning for multiple projects, see [Simultaneous Projects](#simultaneous-projects).
+
+## Simultaneous Projects
+
+> **Warning**
+> 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).
+
+To run multiple projects simultaneously:
+
+1. Create another clone of [Core CMS].
+2. Set up the CMS in that clone.
+3. Set up the other project in that CMS.