From cb6f5b94a5405b305ef3c8b31c74b99b99e3cf07 Mon Sep 17 00:00:00 2001
From: Mandel Olaiya <mandeleolaiya15@icloud.com>
Date: Wed, 24 Jun 2026 00:26:43 +0200
Subject: [PATCH] docs: document production Django command environment

---
 docs/PRODUCTION_DJANGO_COMMANDS.md | 105 +++++++++++++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 docs/PRODUCTION_DJANGO_COMMANDS.md

diff --git a/docs/PRODUCTION_DJANGO_COMMANDS.md b/docs/PRODUCTION_DJANGO_COMMANDS.md
new file mode 100644
index 0000000..f790e52
--- /dev/null
+++ b/docs/PRODUCTION_DJANGO_COMMANDS.md
@@ -0,0 +1,105 @@
+# Production Django Command Wrapper
+
+## Purpose
+
+Manual Django management commands on MandelBlog production do not inherit the
+`mandelstudio-gunicorn.service` systemd drop-in environment.
+
+That matters for Elasticsearch because production search TLS verification is
+enabled only when this environment variable is present:
+
+- `ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt`
+
+Without it, `mandelstudio.settings.env.prd` intentionally falls back to:
+
+- `verify_certs=False`
+
+This does not affect the live site, but it does cause noisy CLI warnings during
+operator commands such as `django check`, `showmigrations`, and shell sessions.
+
+## Standard production command pattern
+
+Use this pattern for manual Django management commands on production:
+
+```bash
+cd /home/www-mandelstudio/mandelstudio && \
+ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt \
+DJANGO_SETTINGS_MODULE=mandelstudio.settings.env.prd \
+/var/lib/virtualenv/mandelstudio/bin/python -m django <command>
+```
+
+## Examples
+
+Run checks:
+
+```bash
+cd /home/www-mandelstudio/mandelstudio && \
+ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt \
+DJANGO_SETTINGS_MODULE=mandelstudio.settings.env.prd \
+/var/lib/virtualenv/mandelstudio/bin/python -m django check
+```
+
+Inspect migrations:
+
+```bash
+cd /home/www-mandelstudio/mandelstudio && \
+ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt \
+DJANGO_SETTINGS_MODULE=mandelstudio.settings.env.prd \
+/var/lib/virtualenv/mandelstudio/bin/python -m django showmigrations
+```
+
+Open a shell:
+
+```bash
+cd /home/www-mandelstudio/mandelstudio && \
+ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt \
+DJANGO_SETTINGS_MODULE=mandelstudio.settings.env.prd \
+/var/lib/virtualenv/mandelstudio/bin/python -m django shell
+```
+
+Run a project command:
+
+```bash
+cd /home/www-mandelstudio/mandelstudio && \
+ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt \
+DJANGO_SETTINGS_MODULE=mandelstudio.settings.env.prd \
+/var/lib/virtualenv/mandelstudio/bin/python -m django apply_priority_seo_metadata --dry-run
+```
+
+## Optional temporary shell helper
+
+For one operator session, you can define a shell helper instead of repeating
+the full command:
+
+```bash
+manage_prd () {
+  cd /home/www-mandelstudio/mandelstudio || return 1
+  ELASTICSEARCH_CA_CERTS=/etc/ssl/certs/elasticsearch-http-ca.crt \
+  DJANGO_SETTINGS_MODULE=mandelstudio.settings.env.prd \
+  /var/lib/virtualenv/mandelstudio/bin/python -m django "$@"
+}
+```
+
+Example:
+
+```bash
+manage_prd check
+manage_prd showmigrations oscar_odin_plugin --plan
+```
+
+## Scope
+
+This is an operator-only convention.
+
+It does not:
+
+- change Django settings
+- change gunicorn runtime behavior
+- restart services
+- alter production data
+- expose secrets or API keys
+
+## Verification
+
+When the command is run with `ELASTICSEARCH_CA_CERTS` set, the Elasticsearch
+`verify_certs=False` warning should not appear in command output.