feat: rewrite README, cleanup non-APCD projects (#172)

TACC · Jun 26, 2023 · 8a08605 · 8a08605
1 parent adc94e9
commit 8a08605
Show file tree

Hide file tree

Showing 14 changed files with 281 additions and 116 deletions.
diff --git a/README.md b/README.md
@@ -2,63 +2,155 @@
 
 Extensions of the [Core CMS] project
 
+## Table of Contents
+
+- [Related Repositories](#related-repositories)
+- [Project Architecture](#project-architecture)
+- [Start Project](#start-project)
+- [Update Project](#update-project)
+- [Develop Project](#develop-project)
+- [Build Project](#build-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 Portal], the base Portal code for TACC WMA CMS Websites
+- [Core Styles], the shared UI pattern code for TACC WMA CMS Websites
 - [Core CMS Resources], the original solution for extensions of the [Core CMS] project
 - [Core Portal Deployments], private repository that facilitates deployments of [Core Portal] images via [Camino] and Jenkins
 
-## Architecture
+## Project Architecture
+
+Within a `/custom_project_dir` can be:
+
+| directory | contents |
+| - | - |
+| `src/apps` | additional Django applications |
+| `src/taccsite_cms` | settings for [Core CMS], additional apps, static assets, or middleware |
+| `src/taccsite_custom` | templates and static assets, organized as Django CMS expects |
+
+## Prerequisites
+
+- [Docker] ≥ v20
+- [Docker Compose] ≥ v1
+- [Python] ≥ v3.8
+
+A CMS project is run using [Docker][1] and [Docker Compose][2]. Both must be pre-installed on the system on which you will run the CMS.
+
+[^2]: On a Mac or a Windows machine, we recommended you install
+[Docker Desktop](https://www.docker.com/products/docker-desktop), which will install both Docker and Docker Compose as well as Docker Machine, which is required to run Docker on Mac/Windows hosts.
 
-- [`.../src/apps`](./src/apps/): Contains any additional Django applications
-- [`.../src/taccsite_cms`](./src/taccsite_cms/): Contains settings files which specify additional apps, static files and middleware to load on top of Core CMS, along with standard Core CMS settings files
-- [`.../src/taccsite_custom`](./src/taccsite_custom/): Contains static assets and templates, organized in the way that Django CMS expects them before imported via `python manage.py collectstatic`.
+> **Notes**
+> See [Core-CMS](https://github.com/TACC/Core-CMS) to verify the latest prerequisites.
 
-## Local Development Setup
+## Start Project
 
-### Prequisites for Running the CMS
+Set up a new local CMS instance.
 
-See [Core-CMS](https://github.com/TACC/Core-CMS#prequisites-for-running-the-cms) "Prequisites for Running the CMS" section.
+0. Python Application:
 
-### Code Configuration
+    In the `custom_project_dir/` you will run, create a `settings_local.py` with content from [Core-CMS `settings_local.example.py`](https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/settings_local.example.py).
 
-#### Settings
+1. Docker Containers:
 
-1. Understand how settings are organized. See [Core-CMS](https://github.com/TACC/Core-CMS#settings) "Settings" section.
-2. **If** the project you work on has a `taccsite_cms/secrets.default.py`, **then**:
+    ```sh
+    cd custom_project_dir
+    make start
+    ```
+
+    ```sh
+    docker exec -it core_cms /bin/bash
+    # This opens a command prompt within the container.
+    ```
+
+2. Django Application:
 
-    ```bash
-    cd custom-project-dir
-    cp taccsite_cms/secrets.default.py taccsite_cms/secrets.py
+    (Run these commands within the container.)
+
+    ```sh
+    python manage.py migrate
+    python manage.py createsuperuser
+    # To use default "Username" and skip "Email address", press Enter at both prompts.
+    # At "Password" prompts, you may use an insecure easy-to-remember password.
+    python manage.py collectstatic --no-input
+    # If the project has no static assets,
+    # (and you have not set up other projects)
+    # then expect output of "0 static files […]"
     ```
-3. Create a `settings_local.py` with content from [Core-CMS `settings_local.example.py`](https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/settings_local.example.py).
 
-## Running the CMS
+3. Django CMS:
+    1. Open http://0.0.0.0:8000/.
+    2. Login with the credentials from step 2.
+    3. Create one CMS page. (With "New page" highlighted, click "Next" button.)
+        - This page will automatically be your local homepage.
+
+> **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).
 
-### Running in Development Mode
+> **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.**
 
-A `Makefile` has been included for convenience in each CMS project. You may use:
+## Update Project
 
-```bash
-cd custom-project-dir
-make start
-```
+Update an existing local CMS instance.
 
-### Running Custom App on a Custom CMS
+1. If CMS Docker image changed, rebuild Docker Containers:
+
+    ```sh
+    cd custom_project_dir
+    make stop
+    make build
+    make start
+    ```
+
+2. If static assets or database models changed[^1], update the Django Application:
+
+    ```sh
+    docker exec -it core_cms /bin/bash
+    ```
+
+    (Run these commands within the container.)
+
+    ```sh
+    python manage.py migrate
+    python manage.py collectstatic --no-input
+    ```
+
+[^1]: Pertinent changes are those in the Core CMS or the custom project. Changes to external assets or databases are not pertinent.
+
+## Run Project
+
+Read the relevant `custom_project_dir/README.md`.
+
+To run multiple projects, first read [Multiple Projects](docs/run-projects.md#multiple-projects).
+
+## Develop Project
+
+### Running a Custom App
 
 - Update `custom_app_settings.py` with relevant content from [TACC/Core-CMS:`/taccsite_cms/custom_app_settings.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/custom_app_settings.example.py).
 - Update `urls_custom.py` with relevant content from [TACC/Core-CMS:`/taccsite_cms/urls_custom.example.py`](https://github.com/TACC/Core-CMS/blob/1d88c35/taccsite_cms/urls_custom.example.py).
 
-## Porting from [Core CMS Resources]
+## Build Project
 
-When porting a downstream CMS project from [Core CMS Resources], the contents of a specific project's custom assets should be copied to [`./custom_project-dir/src/taccsite_custom`](./src/taccsite_custom/). The `settings_custom.py` from the CMS project directory should be moved to [`./custom-project-dir/src/taccsite_cms`](./src/taccsite_cms/) since that is where the file would be placed during a CMS build process from Jenkins.
+Builds result in images that can be deployed. A build alone is not a deploy.
 
+| Automatic Build | Manual Build |
+| - | - |
+| Occurs for each custom project directory (e.g. `demdata_cms`) upon each push to `main`. | Follow [GitHub Docs: GitHub Actions: Running a Workflow](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow#running-a-workflow). |
 
-## Automatic Builds
+> **Note**
+> To check status of any build, see [Actions](https://github.com/TACC/Core-CMS-Custom/actions).
 
-Automatic builds (not deploys) should occur on pushes to each CMS directory e.g. `apcd-cms`.
+## Deploy Project
 
+Follow "Core-CMS-Custom" section of [How To Build & Deploy](https://confluence.tacc.utexas.edu/x/Lo99E).
+
+## Port Project
+
+To port a project from another repository (e.g. [Core CMS Resources]), read [Port Projects](docs/port-projects.md).
 
 <!-- Link Aliases -->
 
@@ -68,3 +160,7 @@ Automatic builds (not deploys) should occur on pushes to each CMS directory e.g.
 [Core Styles]: https://github.com/TACC/tup-ui/tree/main/libs/core-styles
 [Core CMS Resources]: https://github.com/TACC/Core-CMS-Resources
 [Core Portal]: https://github.com/TACC/Core-Portal
+
+[Docker]: https://docs.docker.com/get-docker/
+[Docker Compose]: https://docs.docker.com/compose/install/
+[Python]: https://www.python.org/downloads/
diff --git a/demdata_cms/docker-compose.dev.yml b/demdata_cms/docker-compose.dev.yml
@@ -3,7 +3,7 @@ services:
   cms:
     build: .
     ports:
-      - 8000:8000
+      - 127.0.0.1:8000:8000
     command: ["python3", "manage.py", "runserver", "0.0.0.0:8000"]
     container_name: core_cms
     hostname: core_cms
@@ -44,7 +44,7 @@ services:
       - core_cms_es_data:/usr/share/elasticsearch/data
     container_name: core_cms_elasticsearch
     ports:
-      - 9201:9200
+      - 127.0.0.1:9201:9200
     networks:
       - core_cms_net
 

diff --git a/demdata_cms/src/taccsite_cms/secrets.default.py b/demdata_cms/src/taccsite_cms/secrets.default.py
diff --git a/demdata_cms/src/taccsite_cms/settings_custom.py b/demdata_cms/src/taccsite_cms/settings_custom.py
@@ -24,10 +24,6 @@
     ('demdata-cms/templates/standard.html', 'DEPRECATED Standard (with CSS from TUP)'),
     ('demdata-cms/templates/fullwidth.html', 'DEPRECATED Full Width (with CSS from TUP)'),
 )
-# CMS_TEMPLATES_DIR: {
-#     1: 'demdata_cms/templates/',
-#     2: 'demdata-cms/templates/',
-# }
 
 ########################
 # TACC: BRANDING

diff --git a/docs/port-project.md b/docs/port-project.md
@@ -0,0 +1,79 @@
+# Port Project
+
+## From [Core CMS Resources]
+
+To porting a downstream CMS project from [Core CMS Resources] to this repository:
+
+1. Copy contents:
+    - from [Core CMS Resources] `/taccsite_custom/custom_project_dir`
+    - to `/custom_project_dir/src/taccsite_custom/custom_project_dir`
+
+    > **Warning**
+    > The name **must** use underscores (**not** dashes) to be a valid Python application.
+2. Move custom project settings:
+    - from `/custom_project_dir/src/taccsite_custom/custom_project_dir/settings_custom.py`
+    - to `/custom_project_dir/src/taccsite_cms/settings_custom.py`
+3. If the custom project has any edge cases, review relevant instructions:
+    - [Old Custom Templates Directory](#old-custom-templates-directory)
+    - [Expects CSS Build Step](expects-css-build-step)
+    - [Expects CSS Concatenation](expects-css-concatenation)
+
+### Old Custom Templates Directory
+
+**If** the custom project directory:
+
+- **both** had a name with dashes in [Core CMS Resources]
+- **and** has `templates/standard.html` or `templates/fullwidth.html`
+
+Then:
+
+1. Copy the templates to become placeholders:
+    - from `taccsite_custom/custom_project_dir/templates`
+    - to `taccsite_custom/custom-project-dir/templates`
+
+    > **Warning**
+    > The name `custom-project-dir` **must** match the old name as it was, including dashes.
+2. Edit the placeholder templates to extend the new templates e.g.
+
+    ```django
+    {% extends "custom_project_dir/templates/standard.html" %}
+    ```
+
+### Expects CSS Build Step
+
+**If** the custom project directory expects CSS compilation e.g. has
+
+- `css/src/*.css` with `@import` of a `@tacc/core-styles/` path
+
+Then:
+
+1. Contact https://github.com/wesleyboar.
+
+> **Note**
+> Those imports assume:
+>
+> - Node
+> - NPM package `@tacc/core-styles`
+> - a CSS build script
+>
+> Whether to support those here, and how to port without support for those, has not been decided.
+
+### Expects CSS Concatenation
+
+**If** the custom project directory expects CSS concatenation e.g. has
+
+- `css/src/*.css` with `@import` of a relative path
+
+Then:
+
+1. Rename import paths appended with comment `Core-CMS:/taccsite_cms/…/`:
+    - from `**/*.css`
+    - to `/static/site_cms/css/build/*.css`
+2. Rename relative import paths (e.g. `./**/*.css`):
+    - from `**/*.css`
+    - to `/static/custom_project_dir/css/build/*.css`
+3. Add UI test steps to initial deploy of ported custom project.
+
+<!-- Link Aliases -->
+
+[Core CMS Resources]: https://github.com/TACC/Core-CMS-Resources
diff --git a/docs/run-project.md b/docs/run-project.md
@@ -0,0 +1,51 @@
+# Run Project
+
+## Individual Projects
+
+Read the relevant `custom_project_dir/README.md`.
+
+## 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
+    cd custom_project_dir_1
+    make stop
+    ```
+
+3. Start another project.
+
+    > **Note**
+    > This remove containers, but not volumes e.g. database.
+
+    ```sh
+    cd custom_project_dir_2
+    make start
+    ```
+
+[^1]: If you want to run multiple projects simultaneously, 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).[^2]
+
+To run multiple projects simultaneously:
+
+1. Stop and take down any started projects. (See [Multiple Projects](#multiple-projects) step 2.)
+1. Create a custom `docker-compose.dev.yml` in your project.
+2. Replace all instances of the text `core_cms` with the name of the `custom_project_dir`.
+
+[^2]: Advanced adaptation of these instructions may support retaining database access, et cetera.
+
+[copy a database]: https://confluence.tacc.utexas.edu/pages/viewpage.action?pageId=249135195