feat(settings)!: load client overwrites from settings/overwrites

AGENTS.md

@@ -50,7 +50,7 @@ If you must edit docker-compose to fix a problem specific to your environment, t
 
 #### Settings & Secrets
 
-- **Settings files** are gitignored. Created from `*.example.py` by `bin/setup-cms.sh` or manually.
+- **Client overwrites** live in `taccsite_cms/settings/overwrites/`. Tracked `*.example.py` files are templates; create local `*.py` copies via `bin/setup-cms.sh` or manually (those copies are gitignored). Docker clients should mount that directory, not all of `settings/` (mounting `settings/` overwrites container `settings.py`).
 - **Postgres secret files:** `docker-compose.dev.yml` mounts `./conf/postgres/*.secret` files. These are not required for development and can be ignored.
 
 #### Elasticsearch

README.md

@@ -84,12 +84,12 @@ How to set up a new local CMS instance.
 
 1. Configure [Django] Application:
 
-    Create a `taccsite_cms/settings/*.py` for every `taccsite_cms/settings/*.example.py`, e.g.
+    Create a `taccsite_cms/settings/overwrites/*.py` for every `taccsite_cms/settings/overwrites/*.example.py`, e.g.
 
     ```sh
-    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
+    cp taccsite_cms/settings/overwrites/settings_custom.example.py taccsite_cms/settings/overwrites/settings_custom.py
+    cp taccsite_cms/settings/overwrites/secrets.example.py taccsite_cms/settings/overwrites/secrets.py
+    cp taccsite_cms/settings/overwrites/settings_local.example.py taccsite_cms/settings/overwrites/settings_local.py
     ```
 
 2. Start [Docker] Containers:

bin/setup-cms.sh

@@ -77,10 +77,11 @@ fi
 # Check for required settings files (local first, then remote)
 echo -e "${INF}Checking for required settings files...${RST}"
 FAILED_DOWNLOADS=()
+mkdir -p taccsite_cms/settings/overwrites
 for file in settings_custom settings_local secrets; do
-    settings_file="taccsite_cms/settings/${file}.py"
-    example_file="taccsite_cms/settings/${file}.example.py"
-    url="${BASE_URL}/taccsite_cms/settings/${file}.example.py"
+    settings_file="taccsite_cms/settings/overwrites/${file}.py"
+    example_file="taccsite_cms/settings/overwrites/${file}.example.py"
+    url="${BASE_URL}/taccsite_cms/settings/overwrites/${file}.example.py"
 
     if [ ! -f "$settings_file" ]; then
         if [ -f "$example_file" ]; then

docs/upgrade-project.md

@@ -1,5 +1,6 @@
 # Upgrade Project
 
+- [from v4.40 to v4.41](#from-v440-to-v441)
 - [from v4.39 to v4.40](#from-v439-to-v440)
 - [from v4.28 to v4.29](#from-v428-to-v429)
 - [from v4.N to v4.14](#from-v4n-to-v414)
@@ -45,6 +46,21 @@ Optional:
 
 [^1]: The `cms.settings_custom.py` is committed in [Core Portal Deployments]. A `settings_custom.py` in [Core CMS Custom] is `.gitignore`'d.
 
+## from v4.40 to v4.41
+
+- [Move Client Settings into `settings/overwrites`](#move-client-settings-into-settingsoverwrites)
+
+### Move Client Settings into `settings/overwrites`
+
+Docker clients that mount a host settings directory must use `…/settings/overwrites/`, not `…/settings/`. (Mounting `…/settings/` overwrites the container's `settings.py` and breaks the CMS.)
+
+Files under `…/settings/*.py` (other than this package) are now **not imported**. Move them into `overwrites/` before upgrading.
+
+| | from | to |
+| - | - | - |
+| files | `taccsite_cms/settings/{settings_…,secrets}.py` | `taccsite_cms/settings/overwrites/…` |
+| volume | `taccsite_cms/settings:…/taccsite_cms/settings` | `taccsite_cms/settings/overwrites:…/taccsite_cms/settings/overwrites` |
+
 ## from v4.39 to v4.40
 
 - [Fold `custom_app_settings` into `settings_*`](#fold-custom_app_settings-into-settings_)

taccsite_cms/settings/__init__.py

@@ -1,6 +1,7 @@
 """
 Settings package:
-- override files (settings_custom.py, settings_local.py, etc.)
+- settings.py (core defaults; must remain in this package)
+- overwrites/ (client override files; Docker-mountable)
 - re-export main settings module (for backwards compatibility)
 """
 

taccsite_cms/settings/overwrites/__init__.py

@@ -0,0 +1 @@
+"""Client settings overwrites (Docker-mountable)."""

taccsite_cms/settings/settings_local.example.py → taccsite_cms/settings/overwrites/settings_local.example.py

@@ -2,7 +2,7 @@
 A `settings_local.py` file can override default values in `settings.py` and `settings_custom.py`.
 
 For a detailed walkthrough on overriding settings, see `settings_custom.example.py`:
-https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/settings/settings_custom.example.py
+https://github.com/TACC/Core-CMS/blob/main/taccsite_cms/settings/overwrites/settings_custom.example.py
 '''
 
 # https://docs.djangoproject.com/en/4.2/ref/settings/#allowed-hosts

taccsite_cms/settings/settings.py

@@ -617,30 +617,31 @@ def get_subdirs_as_module_names(path):
 # SETTINGS IMPORT
 ########################
 
+# Prefer `settings/overwrites/`, so Docker clients can mount that dir w/out
+# overwriting this file. Fallbacks remain for older root-level mounts.
+
 try:
-    from taccsite_cms.settings.settings_default import *
+    from taccsite_cms.settings.overwrites.settings_default import *
 except ModuleNotFoundError:
-    # pass
     # DEPRECATED SETTINGS LOCATION
     try:
         from taccsite_cms.settings_default import *
     except ModuleNotFoundError:
         pass
 
 try:
-    from taccsite_cms.settings.settings_custom import *
-    import taccsite_cms.settings.settings_custom as settings_custom
+    from taccsite_cms.settings.overwrites.settings_custom import *
+    import taccsite_cms.settings.overwrites.settings_custom as settings_custom
 except ModuleNotFoundError:
-    # pass
     # DEPRECATED SETTINGS LOCATION
     try:
         from taccsite_cms.settings_custom import *
         import taccsite_cms.settings_custom as settings_custom
     except ModuleNotFoundError:
         settings_custom = []
 
-# NOTE: This is outside try/catch so it supports DEPRECATED SETTINGS LOCATION
-#       (e.g. in TACC/Camino, settings files are directly under taccsite_cms)
+# NOTE: Outside try/catch so it supports DEPRECATED SETTINGS LOCATION
+#       (e.g. TACC/Camino settings files are directly under taccsite_cms/)
 if hasattr(settings_custom, 'EXTRA_INSTALLED_APPS'):
     INSTALLED_APPS += settings_custom.EXTRA_INSTALLED_APPS
 if hasattr(settings_custom, 'EXTRA_STATICFILES_DIRS'):
@@ -649,20 +650,18 @@ def get_subdirs_as_module_names(path):
     MIDDLEWARE += settings_custom.EXTRA_MIDDLEWARE
 
 try:
-    from taccsite_cms.settings.secrets import *
+    from taccsite_cms.settings.overwrites.secrets import *
 except ModuleNotFoundError:
-    # pass
     # DEPRECATED SETTINGS LOCATION
     try:
         from taccsite_cms.secrets import *
     except ModuleNotFoundError:
         pass
 
 try:
-    from taccsite_cms.settings.settings_local import *
-    import taccsite_cms.settings.settings_local as settings_local
+    from taccsite_cms.settings.overwrites.settings_local import *
+    import taccsite_cms.settings.overwrites.settings_local as settings_local
 except ModuleNotFoundError:
-    # pass
     # DEPRECATED SETTINGS LOCATION
     try:
         from taccsite_cms.settings_local import *