bostame/workdock-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: tighten handbook ui copy

Browse Source
This commit is contained in:
Md Bayazid Bostame
2026-03-29 01:48:34 +01:00
parent 80a93bdf70
commit 91188e3138
2 changed files with 13 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
backend/workflows/templates/workflows/developer_handbook.html
View File

@@ -18,7 +18,7 @@
<a class="btn btn-secondary" href="/admin-tools/wiki/">Project Wiki</a>
</div>
</div>
<p class="sub">Engineering runbook for development, deployment, maintenance, and extension of the current company portal deployment.</p>
<p class="sub">Engineering guide for development, deployment, maintenance, and extension of the current portal deployment.</p>
<div class="toc">
<a href="#overview">Overview</a>
@@ -45,9 +45,9 @@
<h2 id="overview">1) Overview</h2>
<div class="box">
<p>This handbook is for developers and maintainers. It documents the actual engineering workflow of the standalone product repository.</p>
<p>This handbook is for developers and maintainers. It documents the engineering workflow of the standalone product repository.</p>
<ul>
<li>Repository: <code>workdock-platform</code> (current local path; legacy compose project name may still be retained for runtime continuity)</li>
<li>Repository: <code>workdock-platform</code></li>
<li>Main stack: Django + Celery + PostgreSQL + Redis + MailHog</li>
<li>Runtime mode: Docker Compose for local development and staging-style operation</li>
<li>Repository-level quick-start guide for future coders: <code>CONTRIBUTING.md</code></li>
@@ -308,7 +308,7 @@ docker compose exec -T web python manage.py run_staging_e2e_check</code></pre>
<li>Use targeted shell checks for render validation when changing templates or routes.</li>
<li>New pages should extend <code>base_shell.html</code> and keep header/frame logic out of page-local templates.</li>
<li>Use real PDF generation tests when changing PDF templates or intro/offboarding document logic.</li>
<li>Use the dedicated Release Checklist page as the final go/no-go runbook before shipping changes.</li>
<li>Use the dedicated Release Checklist page as the final go/no-go guide before shipping changes.</li>
<li>The automated bilingual smoke tests now cover DE/EN request language capture and English email-template rendering.</li>
<li>Onboarding and offboarding request objects now expose explicit processing state and last-error fields. Async tasks are responsible for transitioning <code>submitted → processing → completed/failed</code>.</li>
<li>The Requests Dashboard includes a retry action for failed requests. Retries reset the error text, set the request back to <code>submitted</code>, and enqueue the appropriate Celery task again.</li>
@@ -349,7 +349,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
<li><code>APP_BASE_URL</code> is also appended to trusted CSRF origins automatically.</li>
<li>Use <code>APP_DOMAIN</code> and <code>APP_BASE_URL</code> as the primary deployment-facing values instead of repeatedly editing long host/origin strings.</li>
<li>If you also reach the app by IP address, keep the IP in <code>DJANGO_ALLOWED_HOSTS</code> and, if needed, in <code>DJANGO_CSRF_TRUSTED_ORIGINS</code>.</li>
<li>The dedicated runbook page is available at <code>/admin-tools/deployment-hosts/</code>.</li>
<li>The dedicated host/domain guide is available at <code>/admin-tools/deployment-hosts/</code>.</li>
<li>An <code>Invalid HTTP_HOST header</code> failure happens before normal page routing, so a broken hostname cannot render a custom error page on that same broken host. Use a working host or IP to access the runbook and fix the env file.</li>
</ul>
@@ -361,7 +361,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
<li>Working branch: <code>develop</code>.</li>
<li>Stable branch: <code>main</code>.</li>
<li>GitHub Actions is used for CI.</li>
<li>Current test deployment is done manually from a LAN-connected machine, not from GitHub-hosted runners.</li>
<li>Test deployment is done manually from a LAN-connected machine, not from GitHub-hosted runners.</li>
</ul>
</div>
@@ -408,7 +408,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
</div>
<div class="box">
<h3>Current test server values</h3>
<h3>Test server values</h3>
<ul>
<li>Host: <code>192.168.2.55</code></li>
<li>SSH user: <code>root</code></li>
@@ -445,7 +445,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
</div>
<div class="note">
The current LAN test deployment intentionally uses <code>DJANGO_DEBUG=1</code> in <code>.env.test</code> because the security checks correctly reject insecure cookie settings when <code>DEBUG=0</code> and the deployment is still plain HTTP behind a local test topology. This is acceptable for the test box only. Production must run with HTTPS and <code>DEBUG=0</code>.
The LAN test deployment intentionally uses <code>DJANGO_DEBUG=1</code> in <code>.env.test</code> because the security checks correctly reject insecure cookie settings when <code>DEBUG=0</code> and the deployment is still plain HTTP behind a local test topology. This is acceptable for the test box only. Production must run with HTTPS and <code>DEBUG=0</code>.
</div>
<h2 id="deploy">18) Deployment</h2>
@@ -475,7 +475,7 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
<li>Wait until <code>/healthz/</code> becomes healthy</li>
</ol>
<h3>Manual deploy</h3>
<p>The preferred current test-deployment path is the local helper script from a Mac or another LAN-connected workstation:</p>
<p>The preferred test-deployment path is the local helper script from a Mac or another LAN-connected workstation:</p>
<pre><code>./scripts/deploy_test_from_mac.sh</code></pre>
<p>This script fast-forwards <code>develop</code>, checks that the remote env file exists, syncs the repo to the server with <code>rsync</code>, runs the remote deployment, verifies the health endpoint, and prints the deployed commit hash.</p>
<p>The script explicitly preserves server-local env files such as <code>.env.test</code> and <code>.env.prod</code> so deployment does not wipe machine-specific secrets.</p>

9
backend/workflows/templates/workflows/handbook.html
View File

@@ -15,7 +15,7 @@
<div class="top">
<h1>{% trans "Handbook" %}</h1>
</div>
<p class="sub">{% trans "Single documentation entry point for both operational knowledge and long-term engineering knowledge." %}</p>
<p class="sub">{% trans "Operational and engineering documentation in one place." %}</p>
<div class="grid">
<section class="card">
@@ -26,7 +26,7 @@
<li>{% trans "workflow overview" %}</li>
<li>{% trans "admin tools and system behavior" %}</li>
<li>{% trans "integrations and operations" %}</li>
<li>{% trans "runbook and troubleshooting" %}</li>
<li>{% trans "operations and troubleshooting" %}</li>
</ul>
<div class="actions">
<a class="btn btn-secondary" href="/admin-tools/wiki/">{% trans "Open Project Wiki" %}</a>
@@ -36,7 +36,7 @@
<section class="card">
<div class="eyebrow">{% trans "Engineering" %}</div>
<h2>{% trans "Developer Handbook" %}</h2>
<p>{% trans "Engineering runbook for architecture, branch workflow, deployment, CI/CD, code guidelines, and long-term maintenance." %}</p>
<p>{% trans "Engineering guide for architecture, branch workflow, deployment, CI/CD, code guidelines, and maintenance." %}</p>
<ul>
<li>{% trans "repository and service structure" %}</li>
<li>{% trans "branch workflow and coding guidelines" %}</li>
@@ -46,7 +46,6 @@
</ul>
<div class="actions">
<a class="btn btn-secondary" href="/admin-tools/developer-handbook/">{% trans "Open Developer Handbook" %}</a>
<a class="btn btn-secondary" href="/admin-tools/developer-handbook/#workflow">{% trans "Open Contributor Guide" %}</a>
</div>
</section>
@@ -68,7 +67,7 @@
<section class="card">
<div class="eyebrow">{% trans "Release" %}</div>
<h2>{% trans "Release Checklist" %}</h2>
<p>{% trans "Step-by-step release runbook for rebuilds, migrations, translations, static assets, smoke checks, and rollout verification." %}</p>
<p>{% trans "Step-by-step release guide for rebuilds, migrations, translations, static assets, smoke checks, and rollout verification." %}</p>
<ul>
<li>{% trans "pre-release validation commands" %}</li>
<li>{% trans "translation, static, and migration steps" %}</li>