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' - } -}