-
Notifications
You must be signed in to change notification settings - Fork 1
Locally Develop CMS Portal Docs
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.
- 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
, addINCLUDES_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
The default docker compose file has container name(s) that will conflict with Portal's.
-
(If docker containers are running) Stop (i.e. bring
down
) the docker containers. -
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):
docker-compose -f docker-compose.custom.yml build --no-cache cms
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:
docker-compose -f docker-compose.custom.yml up
- If building from a different CMS image, then rebuild without cache (source):
-
In the CMS container, collect static assets.³
-
(If error contacting database) Stop (i.e. bring
down
) then Restart (i.e. bringup
) the docker containers.⁴ -
(If building assets locally) In the CMS container, run
python manage.py collectstatic --no-input
.
⚠ To preserve independent default setup, change
core_cms
orcore_cms_...
tosad_cms
orsad_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.
-
Have an existing frontera-tech-docs in which you know how to develop.
-
Checkout relevant branch.⁵
-
For each change, follow the next steps:
-
(may be optional) Commit change (to create a new commit has for docker to use as a tag)
-
Run
make build
. -
Save the docker tag from the output:
Truncated Example Output
... taccwma/frontera-tech-docs:1234567 ...
Where
1234567
is a string of characters. -
Repeat "Portal" step 6 at "[…] Values to Change".
-
Wait for build to complete (inside Docker container).
-
(necessary?) Repeat "Portal" step 8.
This method is newly documented, and may be unreliable or not streamlined.
-
For each change, follow the next steps:
-
(may be optional) Commit change (to create a new commit has for docker to use as a tag)
-
Have an existing Frontera_Docs build to use.
-
Save the docker tag from the build output:
Truncated Example Output
... taccwma/frontera-docs:1234567 ...
Where
1234567
is a string of characters. -
Repeat "Portal" step 6 at "[…] Values to Change".
-
Wait for build to complete (inside Docker container).
-
(necessary?) Repeat "Portal" step 8.
-
Have an existing frontera-tech-docs in which you know how to develop.
-
Checkout relevant branch.⁵
-
Copy
docker-compose.yml
asdocker-compose.custom.yml
. -
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
.
- This tells Git to ignore this new directory with no need to edit
-
In the
docker-compose.custom.yml
file, disable volume inservices
:frontera_docs
:volumes
.Volumes to Disable
# - /var/www/frontera/docs:/docs/site
This ensures the built docs stay within the current directory.
-
For each change, follow the next steps:
-
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):
docker-compose -f docker-compose.custom.yml build --no-cache frontera_docs
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:
docker-compose -f docker-compose.custom.yml up --force-recreate --no-deps frontera_docs
- If testing a change to requirements or docker config, then rebuild without cache (source):
-
Wait for build to complete.
-
Have an existing Core-Portal in which you know how to develop.
-
(If docker containers are running) Stop (i.e. bring
down
) the docker containers. -
Ensure relevant CMS secrets are up to date and accurate.
-
Checkout relevant branch.⁵
-
Add symlink in Portal to sync local stand-alone CMS content:
Symlinks to Create
- Replace Directory of Volume Mounts with Symlink to Stand-Alone CMS
Add
rm -rf ${__PATH_TO_LOCAL_CORE_PORTAL__}/server/cms ln -s ${__PATH_TO_LOCAL_CORE_CMS__} ${__PATH_TO_LOCAL_CORE_PORTAL__}/server/cms-standalone
server/cms-standalone
on its own line in.git/info/exclude
.* - (If using "Docs" "Method C") Replace Directory / Volume Mounts with Symlink to Stand-Alone Docs Output
Add
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
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
.
- Replace Directory of Volume Mounts with Symlink to Stand-Alone CMS
-
Update the relevant
docker-compose
config file to sync local stand-alone CMS content:Volumes to Add to and Change in
cms
ContainerTo ensure CMS container mostly uses stand-alone CMS, not Portal's internal CMS.
-
Add these replacements in
services
:cms
:volumes
:../../cms-standalone:/code
../cms/settings_local.py:/code/taccsite_cms/settings_local.py
-
Add new file
server/conf/cms/settings_local.py
with contentINCLUDES_CORE_PORTAL = True
This tells the stand-alone CMS to provide CMS navigation markup (for the Portal).
-
Make these replacements in
services
:cms
:volumes
:-
../../cms-standalone/static:/code/static
→../../cms-standalone/static:/code/static
-
Volumes to Add to
nginx
ContainerTo ensure Nginx container has actual directory contents, not broken symlink(s).
-
Add these volumes in
services
:nginx
:volumes
:../../cms-standalone/static:/srv/www/portal/server/cms/static
../../cms/media:/srv/www/portal/server/cms/media
-
(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. -
-
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
andmake start
commands are not adequate. -
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
andmake start
commands are not adequate. -
(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
-
Start (i.e. bring
up
) the docker containers. -
(If
cms
service has error contacting database) Stop (i.e. bringdown
) then Restart (i.e. bringup
) the docker containers.⁴
Header Content Load Returns Server Error
The CMS service has likely crashed.
- 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 checksettings.py
for syntax error withinINSTALLED_APPS
. - If you see something else, then this document has no specific guidance.
- If you see
- 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
- In Docker Desktop's Dashboard, in the
Either cep.dev
or cep.dev/workbench
Returns Server Error "502 Bad Gateway"
The Nginx service has likely crashed.
- 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
- In Docker Desktop's Dashboard, in the
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 forvolumes
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