Locally Develop CMS Portal Docs - TACC/Core-CMS GitHub Wiki

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.

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

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

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

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

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. 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.

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.⁴

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

³ 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.