diff --git a/README.md b/README.md
index 13aa37c9..3fe2ee25 100644
--- 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).
@@ -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
index 9268e03a..2aeb7843 100644
--- 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
deleted file mode 100644
index fbe11163..00000000
--- a/demdata_cms/src/taccsite_cms/secrets.default.py
+++ /dev/null
@@ -1,19 +0,0 @@
-# SECRET SETTINGS VALUES.
-# (LOCAL TEST INSTANCE)
-
-########################
-# DATABASE SETTINGS
-########################
-
-from taccsite_cms.settings import DATABASES
-
-DATABASES = {
- 'default': {
- 'ENGINE': DATABASES['default']['ENGINE'],
- 'PORT': DATABASES['default']['PORT'],
- 'NAME': DATABASES['default']['NAME'],
- 'USER': DATABASES['default']['USER'],
- 'PASSWORD': DATABASES['default']['PASSWORD'],
- 'HOST': DATABASES['default']['HOST'],
- }
-}
diff --git a/demdata_cms/src/taccsite_cms/settings_custom.py b/demdata_cms/src/taccsite_cms/settings_custom.py
index 1592e93c..5ead7035 100644
--- 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
new file mode 100644
index 00000000..c3091d1b
--- /dev/null
+++ 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.
+
+
+
+[Core CMS Resources]: https://github.com/TACC/Core-CMS-Resources
diff --git a/docs/run-project.md b/docs/run-project.md
new file mode 100644
index 00000000..5b7a2032
--- /dev/null
+++ 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 control + C.
+
+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
diff --git a/example_cms/docker-compose.dev.yml b/example_cms/docker-compose.dev.yml
index ade79ea2..2aeb7843 100644
--- a/example_cms/docker-compose.dev.yml
+++ b/example_cms/docker-compose.dev.yml
@@ -5,8 +5,8 @@ services:
ports:
- 127.0.0.1:8000:8000
command: ["python3", "manage.py", "runserver", "0.0.0.0:8000"]
- container_name: matcssi_cms
- hostname: matcssi_cms
+ container_name: core_cms
+ hostname: core_cms
volumes:
- ./src/apps:/code/apps
- ./src/taccsite_custom:/code/taccsite_custom
@@ -16,7 +16,7 @@ services:
- ./src/taccsite_cms/settings_local.py:/code/taccsite_cms/settings_local.py
- ./src/taccsite_cms/secrets.py:/code/taccsite_cms/secrets.py
networks:
- - matcssi_cms_net
+ - core_cms_net
postgres:
image: postgres:11.5
@@ -26,11 +26,11 @@ services:
- POSTGRES_DB=taccsite
- PGDATA=/var/lib/postgresql/data/taccsite
volumes:
- - matcssi_cms_postgres_data:/var/lib/postgresql/data
- hostname: matcssi_cms_postgres
- container_name: matcssi_cms_postgres
+ - core_cms_postgres_data:/var/lib/postgresql/data
+ hostname: core_cms_postgres
+ container_name: core_cms_postgres
networks:
- - matcssi_cms_net
+ - core_cms_net
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0
@@ -41,16 +41,16 @@ services:
- discovery.type=single-node
volumes:
- ./elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml
- - matcssi_cms_es_data:/usr/share/elasticsearch/data
- container_name: matcssi_cms_elasticsearch
+ - core_cms_es_data:/usr/share/elasticsearch/data
+ container_name: core_cms_elasticsearch
ports:
- 127.0.0.1:9201:9200
networks:
- - matcssi_cms_net
+ - core_cms_net
volumes:
- matcssi_cms_postgres_data:
- matcssi_cms_es_data:
+ core_cms_postgres_data:
+ core_cms_es_data:
networks:
- matcssi_cms_net:
+ core_cms_net:
diff --git a/example_cms/src/taccsite_cms/secrets.default.py b/example_cms/src/taccsite_cms/secrets.default.py
deleted file mode 100644
index 0ea29773..00000000
--- a/example_cms/src/taccsite_cms/secrets.default.py
+++ /dev/null
@@ -1,19 +0,0 @@
-# SECRET SETTINGS VALUES.
-# (LOCAL TEST INSTANCE)
-
-########################
-# DATABASE SETTINGS
-########################
-
-from taccsite_cms.settings import DATABASES
-
-DATABASES = {
- 'default': {
- 'ENGINE': DATABASES['default']['ENGINE'],
- 'PORT': DATABASES['default']['PORT'],
- 'NAME': DATABASES['default']['NAME'],
- 'USER': DATABASES['default']['USER'],
- 'PASSWORD': DATABASES['default']['PASSWORD'],
- 'HOST': 'example_cms_postgres'
- }
-}
diff --git a/example_cms/src/taccsite_custom/matcssi_cms/__init__.py b/example_cms/src/taccsite_custom/example_cms/__init__.py
similarity index 100%
rename from example_cms/src/taccsite_custom/matcssi_cms/__init__.py
rename to example_cms/src/taccsite_custom/example_cms/__init__.py
diff --git a/example_cms/src/taccsite_custom/matcssi_cms/static/matcssi_cms/img/favicons/favicon.ico b/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/favicons/favicon.ico
similarity index 100%
rename from example_cms/src/taccsite_custom/matcssi_cms/static/matcssi_cms/img/favicons/favicon.ico
rename to example_cms/src/taccsite_custom/example_cms/static/example_cms/img/favicons/favicon.ico
diff --git a/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/org_logos/portal.png b/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/org_logos/portal.png
new file mode 100644
index 00000000..3ec46382
Binary files /dev/null and b/example_cms/src/taccsite_custom/example_cms/static/example_cms/img/org_logos/portal.png differ
diff --git a/example_cms/src/taccsite_custom/matcssi_cms/static/matcssi_cms/img/org_logos/matcssi.png b/example_cms/src/taccsite_custom/matcssi_cms/static/matcssi_cms/img/org_logos/matcssi.png
deleted file mode 100644
index 4f98b177..00000000
Binary files a/example_cms/src/taccsite_custom/matcssi_cms/static/matcssi_cms/img/org_logos/matcssi.png and /dev/null differ
diff --git a/matcssi_cms/docker-compose.dev.yml b/matcssi_cms/docker-compose.dev.yml
index ade79ea2..2aeb7843 100644
--- a/matcssi_cms/docker-compose.dev.yml
+++ b/matcssi_cms/docker-compose.dev.yml
@@ -5,8 +5,8 @@ services:
ports:
- 127.0.0.1:8000:8000
command: ["python3", "manage.py", "runserver", "0.0.0.0:8000"]
- container_name: matcssi_cms
- hostname: matcssi_cms
+ container_name: core_cms
+ hostname: core_cms
volumes:
- ./src/apps:/code/apps
- ./src/taccsite_custom:/code/taccsite_custom
@@ -16,7 +16,7 @@ services:
- ./src/taccsite_cms/settings_local.py:/code/taccsite_cms/settings_local.py
- ./src/taccsite_cms/secrets.py:/code/taccsite_cms/secrets.py
networks:
- - matcssi_cms_net
+ - core_cms_net
postgres:
image: postgres:11.5
@@ -26,11 +26,11 @@ services:
- POSTGRES_DB=taccsite
- PGDATA=/var/lib/postgresql/data/taccsite
volumes:
- - matcssi_cms_postgres_data:/var/lib/postgresql/data
- hostname: matcssi_cms_postgres
- container_name: matcssi_cms_postgres
+ - core_cms_postgres_data:/var/lib/postgresql/data
+ hostname: core_cms_postgres
+ container_name: core_cms_postgres
networks:
- - matcssi_cms_net
+ - core_cms_net
elasticsearch:
image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0
@@ -41,16 +41,16 @@ services:
- discovery.type=single-node
volumes:
- ./elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml
- - matcssi_cms_es_data:/usr/share/elasticsearch/data
- container_name: matcssi_cms_elasticsearch
+ - core_cms_es_data:/usr/share/elasticsearch/data
+ container_name: core_cms_elasticsearch
ports:
- 127.0.0.1:9201:9200
networks:
- - matcssi_cms_net
+ - core_cms_net
volumes:
- matcssi_cms_postgres_data:
- matcssi_cms_es_data:
+ core_cms_postgres_data:
+ core_cms_es_data:
networks:
- matcssi_cms_net:
+ core_cms_net:
diff --git a/matcssi_cms/src/taccsite_cms/secrets.default.py b/matcssi_cms/src/taccsite_cms/secrets.default.py
deleted file mode 100644
index 335c1885..00000000
--- a/matcssi_cms/src/taccsite_cms/secrets.default.py
+++ /dev/null
@@ -1,19 +0,0 @@
-# SECRET SETTINGS VALUES.
-# (LOCAL TEST INSTANCE)
-
-########################
-# DATABASE SETTINGS
-########################
-
-from taccsite_cms.settings import DATABASES
-
-DATABASES = {
- 'default': {
- 'ENGINE': DATABASES['default']['ENGINE'],
- 'PORT': DATABASES['default']['PORT'],
- 'NAME': DATABASES['default']['NAME'],
- 'USER': DATABASES['default']['USER'],
- 'PASSWORD': DATABASES['default']['PASSWORD'],
- 'HOST': 'matcssi_cms_postgres'
- }
-}