Skip to content

Locally Develop CMS Portal Docs

Jump to bottom
W. Bomar edited this page Nov 29, 2021 · 90 revisions

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 secrets.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:
  • change the logo for each using their respective secrets.py files

CMS

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

If you used make build and make start, you are using a docker compose file with container name(s) that will conflict with Portal.

  1. Copy docker-compose.dev.yml as docker-compose.custom.yml.

  2. In the docker-compose.custom.yml file, replace core_cms with sad_cms, e.g.:

    • core_cms → sad_cms
    • core_cms_postgres → sad_cms_postgres
    • core_cms_postgres_data → sad_cms_postgres_data
    • ...

  3. (If no taccsite_cms/secrets.py file),

    1. Create taccsite_cms/secrets.py.
    2. Copy DATABASES = { ... } from taccsite_cms/settings.py to taccsite_cms/secrets.py.

  4. In the taccsite_cms/settings.local.py file, replace "core_cms_postgres" with "sad_cms_postgres".

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

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

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

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

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

Note: Commands or changes that reference core_cms or core_cms_... should instead be sad_cms or sad_cms_....

Docs

Method A

  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. 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. Repeat "Portal" step 6.

Method C

This method is the oldest Wes has documented, but it has been unreliable for him.

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

  2. Checkout relevant branch.⁵

  3. (might be necessary) In the relevant docker-compose config file, disable in the services:cms:volumes directories not to sync.

    Volumes to Disable 
          # - /var/www/frontera/docs:/docs/site

    This ensures the built docs stay within the current directory.

  4. For each change, follow the next steps:

  5. In the environment*, run mkdocs build.

    * The environment can be your local machine (a Python virtual environment is recommended) or a running docker container (but the Docs docker container is closed after build is complete—last confirmed on 2021-08).

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 Nginx

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

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

      • ../../cms/ → ../../cms-standalone/

    2. Make these replacements in services:nginx:volumes:

      • ../../cms/ → ../../cms-standalone/*

      * Except for ../../cms/media, because it was not changed in services:cms:volumes.\

    3. (If using "Docs" "Method C") Make these replacements in services:nginx:volumes:

      • ../../docs/ → ../../docs-standalone/
    Values to Change (only for "Docs" "Method A" and "Method B")

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

  7. Rebuild 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. Rebuild 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) Rebuild 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. docker exec -it core_portal_cms /bin/bash
    • pip3 install --no-cache-dir -r requirements.txt
    • exit
  3. 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.debug.yml restart cms
Either cep.dev or cep.dev/workbench Returns 502 Server Error

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

TACC ACI WMA Core-CMS Project Documentation

Clone this wiki locally