README.md

TACC Core CMS

The base CMS code for TACC WMA Workspace Portals & Websites

Related Repositories

• Camino, a Docker container-based deployment scheme
• 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 custom CMS code for TACC WMA CMS Websites
• Core Portal Deployments, private repository that facilitates deployments of Core Portal images via Camino and Jenkins

Local Development Setup

Prequisites for Running the CMS

• Docker 20.10.7
• Docker Compose 1.29.2
• Python 3.6.8
• Nodejs 16.x (LTS)

The Core CMS can be run using Docker and Docker Compose. You will need both Docker and Docker Compose pre-installed on the system you wish to run the CMS on.

If you are on a Mac or a Windows machine, the recommended method is to install 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.

Code Configuration

After you clone the repository locally, there are several configuration steps required to prepare the project.

Required

1. Initialize / Update submodules:
   1. git submodule init
      _{Adds Core CMS Resources repo as submodule at taccsite_custom/. Only necessary once per parent repo clone.}
   2. git submodule update
      _{Downloads code from pinned commit of Core CMS Resources repo to taccsite_custom/.}

Optional

Settings may be customized piecemeal by adding, in any of these files, only the settings to change:

*	File	Usage
1	secrets.py	Sensitive setting we would never commit to GitHub, like DB creds and secret values
2	settings_custom.py	Settings specific to one CMS project (you can symlink to an existing file)†
3	settings_local.py	Settings specific to a local development environment, not intended for others

_{* This is a "Precedence" column. A file with a higher precedence value overrides one of a lower value.
† See If You Want to Test Custom Resources per CMS Project.}

If You Run this CMS Independent of Core Portal

Add INCLUDES_CORE_PORTAL = False to taccsite_cms/settings_local.py (to avoid Not Found: core/markup/nav/).

If You Want to Use This With Local Core Portal Instance

Follow How to Use a Custom Docker Compose File.

If You Want to Test Custom Resources per CMS Project

All CMS projects (besides the stand-alone CMS core), store project-specific resources in the taccsite_custom submodule.

1. Create a taccsite_cms/settings_custom.py symlink to taccsite_custom/name-of-project/settings_custom.py.*†
2. Build project-specific static files. See Static Files.

_{* Where name-of-project matches a directory from /taccsite_custom.
† Example (from project root): ln -s ../taccsite_custom/name-of-project/settings_custom.py taccsite_cms/settings_custom.py*}

Running the CMS

1. Build the CMS and database images:

   docker-compose build

   Or, if you have a docker-compose.custom.yml, then:

   docker-compose -f docker-compose.custom.yml build

2. Create and run the CMS and database containers:

   docker-compose up

   Or, if you have a docker-compose.custom.yml, then:

   docker-compose -f docker-compose.custom.yml up

3. Start a bash session into the CMS container:

   Notice: If you have a docker-compose.custom.yml, then change core_cms in this command to the cms: container_name in the docker-compose.custom.yml.

   docker exec -it core_cms /bin/bash

4. Run migrations for Django CMS:

   python manage.py migrate

   This is like a Django CMS wrapper around Django migrations.

5. Create a superuser for Django CMS:

   Notice: A TACC username is required for LDAP access, but any password can be used. The password will be validated against LDAP first, if that fails, it will be validated against the password assigned during the following command's interface. For production, create a strong password.

   python manage.py createsuperuser

   You may create additional accounts as needed.

   Notice: To log in with a TACC account using LDAP, create the account using the TACC username, then (as an admin or superuser) assign staff and/or superuser privileges. The assigned password can be any password and does not need to be sent to the user. The CMS will not attempt to validate with the assigned password unless LDAP authentication fails. For production, create a strong password.

6. Collect static files for Django:

   python manage.py collectstatic

   If DEBUG is set to True, then this is automated via python manage.py runserver.

7. Login to the admin web interface.

   The CMS admin site should now be accessible at http://localhost:8000/admin.\*

   You may log in as the superuser created via the createsuperuser command in an earlier step.

   _{* Or at the port defined in a docker-compose.custom.yml.}

8. Create the first page of your local CMS.

   Warning: The CMS install will be fresh i.e. the CMS will not be populated with production content.

   You may create pages as needed to test CMS development.

   In the future, you will be able to clone content from other CMS instances.

Static Files

If you changes files in any static/ directory, you may need to follow some of these steps.

Notice: We configured Django to ignore src directories during collectstatic, so templates can not directly load source files.

Quick Start

0. (assumed) Install missing or out-of-date Node dependencies.*
1. (optional) Make changes to /taccsite_custom/name-of-project/static/name-of-project/css/src files. †‡
2. Build static files from source files.
   Via shell:
   1. npm run build
      or
      npm run build --project=name-of-project †
      or
      npm run build (...) --build-id=optional-identifier §
3. (to debug) Review respective files' content in
   /taccsite_custom/name-of-project/static/name-of-project/css/build. †
4. "Collect" static files. See How to Collect Static Files.
5. (to debug) Confirm respective output changed in:
   /taccsite_cms/static/site_cms/css/build
   and/or
   /taccsite_custom/static/name-of-project/css/build †

_{* The recommended command to install expected dependencies is npm ci.
† Where name-of-project matches a directory from /taccsite_custom.
‡ To commit such changes, see Changing Custom Resources.
§ A build ID can tag files (e.g. preserved comment in stylesheet).}

How to Build Static Files

Certain static files are built from source files in src directories to compiled files in build directories.

1. Build static resources: *

   npm run build

   or †

   npm run build --project=name-of-project

_{* You should run these commands in the container from /code/. See Running Commands in Container.
† Where name-of-project matches a directory from /taccsite_custom.}

How to Collect Static Files

Whenever static files are changed, the CMS must be manually told to serve them.*

1. Collect static files for Django: *

   python manage.py collectstatic --no-input

_{* You should run these commands in the container from /code/. See Running Commands in Container.}

Changing Custom Resources

If you need to get the latest files into /taccsite_custom from Core CMS Resources:

1. How to Change Submodule Branch Commit

If you need to change files within /taccsite_custom:

1. Follow instructions and directory structure of example-cms.
2. Create/Edit files in a child directory of /taccsite_custom.
3. Reference other projects in /taccsite_custom.
4. (to test static file changes) Build static files.*
5. (to test template changes) Restart server.
6. Commit changes:
   1. In /taccsite_custom submodule repo, commit changes (not to main branch).
   2. In this parent repo, add /taccsite_custom change.
   3. In this parent repo, commit changes (not to main branch).

_{To learn more, see Static Files.}

Customizing Text in Admin UI

1. Create file /taccsite_cms/locale/en/LC_MESSAGES/django.po.

2. Add to the file only the strings to translate and the appropriate comments for that string.

3. Build the .mo file: *

   django-admin compilemessages

4. Restart the CMS server.[^3]†

_{* You should run this command in the container from /code/. See Running Commands in Container.
† See Restarting the CMS Server.}

UI Pattern Demo

This demo shows Core Styles with site.css from either Core CMS or a Core CMS Resources project.

1. Build UI patterns demo: *

   npm run build:css-demo --project=name-of-project

2. Serve the demo:

   npm run start:css-demo

_{* Where name-of-project is "core-cms" or matches a directory from /taccsite_custom. A project name is required.}

Running Commands in Container

If using docker-compose.yml then run certain commands via shell within container (because files are not re-synced with local machine).

If using docker-compose.dev.yml or docker-compose.custom.yml then run certain commands either on local machine or via shell within container (because files are re-synced with local machine).

To enter shell within container: *

docker exec -it core_cms /bin/bash

_{* If using docker-compose.custom.yml, then change core_cms to its cms: container_name.}

Restarting the CMS Server

See How to Restart the CMS Server.

Setting up Search Index

See How to Build Search Index.

Linting and Formatting Conventions

Not standardized. See (internal) Formatting & Linting.

Testing

Server-side CMS plugin testing is run through Python. Start docker container first by docker exec -it core_cms bash, Then run python manage.py test path.to-dir.with.tests* from the project root folder to run backend tests and display a report at the bottom of the output.

_{* To run tests without console logging, run python manage.py test path.to-dir.with.tests --nomigrations.}

Test Coverage

Coverage is sent to codecov on commits to the repo (see Github Actions for branch to see branch coverage). Ideally we only merge positive code coverage changes to main.

Production Deployment

The Core CMS runs in a Docker container as part of a set of services managed with Docker Compose.

CMS images are built by Jenkins and published to the Docker Hub repo.

To update the CMS in production or dev, the corresponding Core Portal Deployments env file should be updated with a tag matching an image previously built and published to the taccwma/core-cms repo.

Deployments are initiated via Jenkins and orchestrated, tracked, and directed by Camino on the target server.

Deployment Steps

1. Build and publish portal image with Jenkins
2. Update deployment settings, particularly the CMS_TAG environment variable in Core Portal Deployments with new tag name
3. Deploy new image with Jenkins

Contributing

Development Workflow

We use a modifed version of GitFlow as our development workflow. Our development site (accessible behind the TACC Network) is always up-to-date with main, while the production site is built to a hashed commit tag.

• Feature branches contain major updates, bug fixes, and hot fixes with respective branch prefixes:
  • task/ for features and updates
  • bug/ for bugfixes
  • fix/ for hotfixes

Testing Core Styles Changes Locally

See Locally Develop CMS and Styles.

Best Practices

Sign your commits (see this link for help)

Release Workflow

Only appointed team members may release versions.

1. Create new branch for version bump.
2. Update CHANGELOG.md.
3. Update version via npm version N.N.N (run from .../core-styles/).
4. Commit, push, PR, review, merge.
5. Tag version i.e.
   1. git tag -a vN.N.N -m "vN.N.N"
   2. git push origin vN.N.N
6. Author a release via GitHub (choose the tag from previous step).

Resources

• Learn Markdown
• Tapis Project (Formerly Agave)