Locally Develop CMS Portal Docs

Audience

Developers who already have a https://github.com/TACC/Core-Portal/ running, but want to run and develop on a https://github.com/TACC/Core-CMS/ and taccaci/frontera-tech-docs simulataneously.

⚠️ There may be a simpler solution. Wesley B has not revisited this since having learned more Docker knowledge.

Setup

Notice

This setup will result in two CMS instances, but one CMS directory with static assets, templates, settings, et cetera.

• one set of CMS static assets, templates, and settings (shared between standalone CMS and Portal CMS)
• two sets of CMS pages (one each for standalone CMS and Portal CMS) i.e. two databases and /media's
• one Docs /docs (shared between standalone Docs and Portal Docs)
• two sets of docker image layers for Docs (one each for standalone Docs and Portal Docs)

Consider distinguishing standalone CMS and Portal CMS, because they will look identical.

Suggestions

• in standalone CMS settings_local.py, add INCLUDES_CORE_PORTAL = False
• add unique homepage content to both CMS homepages
• add a link to the other CMS in the navigation of each:
  • "Portal CMS → S.A.D. CMS" (use "Advanced settings" to redirect to http://localhost:8000)
  • "S.A.D. CMS → Portal CMS" (use "Advanced settings" to redirect to https://cep.dev)
• change the logo for each using their respective settings_local.py files

CMS

If You Did Not Use a Custom Docker Compose File, Then Do So

The default docker compose file has container name(s) that will conflict with Portal's.

1. Follow How to Use a Custom Docker Compose File.

2. (If docker containers are running) Stop (i.e. bring down) the docker containers.

3. Rebuild and/or Restart the cms docker container using custom docker compose file.

   Commands to Run

   • If building from a different CMS image, then rebuild without cache (source):
     1. docker-compose -f docker-compose.custom.yml build --no-cache cms
     2. docker-compose -f docker-compose.custom.yml up --force-recreate --no-deps -d cms
   • If building from the same CMS image, then you may simply restart containers:
     1. docker-compose -f docker-compose.custom.yml up

4. In the CMS container, collect static assets.³

5. (If error contacting database) Stop (i.e. bring down) then Restart (i.e. bring up) the docker containers.⁴

6. (If building assets locally) In the CMS container, run python manage.py collectstatic --no-input.

⚠ To preserve independent default setup, change core_cms or core_cms_... to sad_cms or sad_cms_... in:

• the file docker-compose.custom.yml (edit file)
• the file secrets.py (edit file)
• commands you copy from README.md

Docs

Method A

This method is newly documented, and may be unreliable or not streamlined.

1. Have an existing frontera-tech-docs in which you know how to develop.

2. Checkout relevant branch.⁵

3. For each change, follow the next steps:

4. (may be optional) Commit change (to create a new commit has for docker to use as a tag)

5. Run make build.

6. Save the docker tag from the output:

   Truncated Example Output

   ... taccwma/frontera-tech-docs:1234567 ...

   Where 1234567 is a string of characters.

7. Repeat "Portal" step 6 at "[…] Values to Change".

8. Wait for build to complete (inside Docker container).

9. (necessary?) Repeat "Portal" step 8.

Method B

This method is newly documented, and may be unreliable or not streamlined.

1. For each change, follow the next steps:

2. (may be optional) Commit change (to create a new commit has for docker to use as a tag)

3. Have an existing Frontera_Docs build to use.

4. Save the docker tag from the build output:

   Truncated Example Output

   ... taccwma/frontera-docs:1234567 ...

   Where 1234567 is a string of characters.

5. Repeat "Portal" step 6 at "[…] Values to Change".

6. Wait for build to complete (inside Docker container).

7. (necessary?) Repeat "Portal" step 8.

Method C

1. Have an existing frontera-tech-docs in which you know how to develop.

2. Checkout relevant branch.⁵

3. Copy docker-compose.yml as docker-compose.custom.yml.

4. Add docker-compose.custom.yml on its own line in .git/info/exclude.*

   • This tells Git to ignore this new directory with no need to edit .gitignore.

5. In the docker-compose.custom.yml file, disable volume in services:frontera_docs:volumes.

   Volumes to Disable

         # - /var/www/frontera/docs:/docs/site
   

   This ensures the built docs stay within the current directory.

6. For each change, follow the next steps:

7. Rebuild and/or Restart the docs docker container without cache. (source)

   Commands to Run

   • If testing a change to requirements or docker config, then rebuild without cache (source):
     1. docker-compose -f docker-compose.custom.yml build --no-cache frontera_docs
     2. docker-compose -f docker-compose.custom.yml up --force-recreate --no-deps frontera_docs
   • If testing a change to just docs and assets, then you may recreate and restart:
     1. docker-compose -f docker-compose.custom.yml up --force-recreate --no-deps frontera_docs

8. Wait for build to complete.

Portal

1. Have an existing Core-Portal in which you know how to develop.

2. (If docker containers are running) Stop (i.e. bring down) the docker containers.

3. Ensure relevant CMS secrets are up to date and accurate.

4. Checkout relevant branch.⁵

5. Add symlink in Portal to sync local stand-alone CMS content:

   Symlinks to Create

   1. Replace Directory of Volume Mounts with Symlink to Stand-Alone CMS

      rm -rf ${__PATH_TO_LOCAL_CORE_PORTAL__}/server/cms
      ln -s ${__PATH_TO_LOCAL_CORE_CMS__} ${__PATH_TO_LOCAL_CORE_PORTAL__}/server/cms-standalone
      

      Add server/cms-standalone on its own line in .git/info/exclude.*
   2. (If using "Docs" "Method C") Replace Directory / Volume Mounts with Symlink to Stand-Alone Docs Output

      rm -rf ${__PATH_TO_LOCAL_CORE_PORTAL__}/server/docs
      ln -s ${__PATH_TO_LOCAL_DOCS_REPO__}/site ${__PATH_TO_LOCAL_CORE_PORTAL__}/server/docs-standalone
      

      Add server/docs-standalone on its own line in .git/info/exclude.*

   • This tells Git to ignore this new directory with no need to edit .gitignore.

6. Update the relevant docker-compose config file to sync local stand-alone CMS content:

   Volumes to Add to and Change in cms Container

   To ensure CMS container mostly uses stand-alone CMS, not Portal's internal CMS.

   1. Add these replacements in services:cms:volumes:

      • ../../cms-standalone:/code
      • ../cms/settings_local.py:/code/taccsite_cms/settings_local.py

   2. Add new file server/conf/cms/settings_local.py with content

      INCLUDES_CORE_PORTAL = True
      

      This tells the stand-alone CMS to provide CMS navigation markup (for the Portal).

   3. Make these replacements in services:cms:volumes:

      • ../../cms-standalone/static:/code/static → ../../cms-standalone/static:/code/static
   Volumes to Add to nginx Container

   To ensure Nginx container has actual directory contents, not broken symlink(s).

   1. Add these volumes in services:nginx:volumes:

      • ../../cms-standalone/static:/srv/www/portal/server/cms/static
      • ../../cms/media:/srv/www/portal/server/cms/media

   2. (If using "Docs" "Method C") Add these volumes in services:nginx:volumes:

      • ../../docs-standalone:/srv/www/portal/server/docs
   Values to Change in docs Container (only for "Docs" "Method A" and "Method B")

   Replace the services:docs:image with the one from "Docs" "Method A/B" step 4.

7. Restart the cms docker container without cache. (source)

   Commands to Run

   docker-compose -f server/conf/docker/docker-compose-dev.all.debug.yml up --force-recreate --no-deps -d cms
   

   The make stop and make start commands are not adequate.

8. Restart the docs docker container without cache. (source)

   Commands to Run

   docker-compose -f server/conf/docker/docker-compose-dev.all.debug.yml up --force-recreate --no-deps -d docs
   

   The make stop and make start commands are not adequate.

9. (might be necessary) (could be overkill) Restart the nginx docker container without cache. (source)

   Commands to Run

   docker-compose -f server/conf/docker/docker-compose-dev.all.debug.yml up --force-recreate --no-deps -d nginx
   

10. Start (i.e. bring up) the docker containers.

11. (If cms service has error contacting database) Stop (i.e. bring down) then Restart (i.e. bring up) the docker containers.⁴

Troubleshooting

Header Content Load Returns Server Error

The CMS service has likely crashed.

1. Check CMS container logs.
   • If you see ModuleNotFoundError: No module named 'test_without_migrations', then continue to next step.
   • If you see ModuleNotFoundError: No module named 'some_module.you_know_exists', then check settings.py for syntax error within INSTALLED_APPS.
   • If you see something else, then this document has no specific guidance.
2. Restart the CMS service. Methods:
   • In Docker Desktop's Dashboard, in the core_portal_cms, click "↻" button.
   • docker-compose -f server/conf/docker/docker-compose-dev.all.custom.yml restart cms

Either cep.dev or cep.dev/workbench Returns Server Error "502 Bad Gateway"

The Nginx service has likely crashed.

1. Restart the Nginx service:
   • In Docker Desktop's Dashboard, in the core_portal_nginx, click "↻" button.
   • docker-compose -f server/conf/docker/docker-compose-dev.all.custom.yml restart nginx

Workflow Changes

Build CMS Static Assets

To make sure Stand-Alone CMS and Portal CMS both receive re-built CSS assets, run:

npm run build && docker exec -it sad_cms python3 manage.py collectstatic --no-input && docker exec -it core_portal_cms python3 manage.py collectstatic --no-input

Footnotes

³ When you rebuild, the Node build output may be absent (because - .:/code entry for volumes overwrites containers files originating from image).

⁴ The first start may hit a database contact error, Name or service not known. The second start should not.

⁵ So that the CMS test is against the correct Portal code:

• If the CMS branch has an accompanying Portal branch, then checkout that accompanying Portal branch.
• If the CMS branch does not have an accompanying Portal branch, then checkout main.