TACC Core CMS

https://cep.tacc.utexas.edu/

The base CMS code for TACC WMA Workspace Portals & Websites

Table of Contents

• Related Repositories
• Project Architecture
• Prerequisites
• Getting Started
• Update Project
• Manage Dependencies
• Develop Project
  • Develop a Custom Project
  • Develop a Custom App/Plugin
• Test Project
• Debug Project
• Run Another Project Instance
• Build & Deploy Project
• Contributing
• Resources

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 Template, a template for creating new TACC WMA CMS projects
• Core CMS Custom, the new solution for extensions of the Core CMS project
• Core Portal Deployments, private repository that facilitates deployments of Core Portal images via Camino and Jenkins

Project Architecture

directory	contents
apps	additional Django applications
bin	scripts e.g. build CSS
taccsite_cms	customize & configure Django CMS

Prerequisites

• Docker
  • Docker Engine ≥ v20
  • Docker Compose

Important We recommend you install the Docker Desktop application. Alternatively, you may install both Docker Engine and Docker Compose.

Getting Started

How to set up a new local CMS instance.

Important To develop a new or existing custom CMS website for a TACC client, do not clone this repository. Instead, read Develop a Custom Project. To develop on the Core CMS (upon which our other CMS are built) continute reading.

Quick Setup

0. Enter CMS project:

   cd cms
   

1. (optional) To remove previous setup entirely:

   make clean
   

2. Run the setup script:

   make setup
   

   You will be prompted for information.

   To set the superuser password non-interactively:

   DJANGO_SUPERUSER_PASSWORD=yourpass make setup
   

3. Add Content.

Manual Setup

[!NOTE] If Quick Start process fails, report the error to your team, and follow these steps for now.

1. Configure Django Application:

   Create a taccsite_cms/settings/*.py for every taccsite_cms/settings/*.example.py, e.g.

   cp taccsite_cms/settings/settings_custom.example.py taccsite_cms/settings/settings_custom.py
   cp taccsite_cms/settings/secrets.example.py taccsite_cms/settings/secrets.py
   cp taccsite_cms/settings/settings_local.example.py taccsite_cms/settings/settings_local.py
   

2. Start Docker Containers:

   make start
   

   Note This will make the terminal window busy. To run commands after this, either open a new terminal window or run make start ARGS="--detach" instead.

3. Build CSS:

   docker run --rm -v "$(pwd):/code" -w /code node:20 sh -c "npm ci && npm run build"
   

   Note If you will develop thus rebuild stylesheets often, use a local Node installation and run npm ci once, then npm run build as needed.

4. Prepare Django Application:

   docker exec -it core_cms /bin/bash
   # This opens a command prompt within the container
   

   (Run these commands within the container.)

   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 easy-to-remember password.
   python manage.py collectstatic --no-input
   
   

5. Add Content.

Add Content

1. Open http://localhost:8000/.
2. Login with the credentials you defined in step 2.
3. Create one CMS page.
   (With "New page" highlighted, click "Next" button.)
   • This page will automatically be your local homepage.

Important A local machine CMS will be empty. It will not have content from staging nor production. If you need that, follow and adapt instructions to replicate a CMS database. This requires high-level server access or somone to give you a copy of the content.

Note A local machine CMS does not include nor integrate with an instance of Core Portal. To attempt to do that, follow How to Use a Custom Docker Compose File and Locally Develop CMS Portal Docs. Help welcome.

Update Project

To update an existing CMS instance.

New Major Version (or v3.12)

Read Upgrade Project for developer instructions.

New Minor or Patch Version (or Branch)

make stop
make build
make start

To only update as necessary, or update since uncommon changes, read Command Sequences.

Manage Dependencies

Read Manage Dependencies.

Develop Project

Read Django CMS User Guide for CMS user instructions.

Read Develop Project for developer instructions.

Develop a Custom Project

To develop a new or existing custom CMS website for a client, read Develop a Custom Project.

Develop a Custom App/Plugin

To develop a new or existing Django CMS app or plugin for a client, read Develop a Custom App/Plugin.

Test Project

Read Testing for miscellaneous workflows.

Debug Project

Read Debug Project for miscellaneous tips.

Run Another Project Instance

Read Run Another Project Instance when you need a second dev server (shared or isolated database).

Build & Deploy Project

Follow "Core-CMS" section of How To Build & Deploy.

Contributing

To contribute, first read How to Contribute.

Resources

Commands

command	reference
docker exec -it core_cms /bin/bash	docker
python manage.py migrate	django cms, django
python manage.py collectstatic	django
python manage.py createsuperuser	django cms, django