docs: simplify handbook ci cd instructions
This commit is contained in:
Md Bayazid Bostame
@@ -287,73 +287,98 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS</code></pre>
|
||||
</ul>
|
||||
|
||||
<h2 id="cicd">14) CI/CD</h2>
|
||||
<ul>
|
||||
<li>Repository model: one private GitHub repository, not separate dev/prod repositories.</li>
|
||||
<li>Branch model: <code>develop</code> for the test deployment, <code>main</code> reserved for production.</li>
|
||||
<li>Current test workflow file: <code>.github/workflows/deploy-test.yml</code>.</li>
|
||||
<li>Current production workflow file: <code>.github/workflows/deploy-prod.yml</code>.</li>
|
||||
<li>GitHub Actions uploads the working tree to the server over SSH. The server does not clone from GitHub.</li>
|
||||
<li>This is intentional for a private repository: it removes the need to store GitHub deploy keys on the target server.</li>
|
||||
<li>However, GitHub-hosted runners cannot reach a LAN-only private IP like <code>192.168.2.55</code>. For the current local test server, the correct CD path is manual deployment from a LAN machine or a self-hosted runner inside the same network.</li>
|
||||
</ul>
|
||||
<h3>GitHub Environments</h3>
|
||||
<ul>
|
||||
<li>Create GitHub environments named <code>development</code> and <code>production</code>.</li>
|
||||
<li><strong>Development</strong> secrets:
|
||||
<ul>
|
||||
<li><code>TEST_DEPLOY_HOST</code></li>
|
||||
<li><code>TEST_DEPLOY_USER</code></li>
|
||||
<li><code>TEST_DEPLOY_PORT</code></li>
|
||||
<li><code>TEST_DEPLOY_PATH</code></li>
|
||||
<li><code>TEST_DEPLOY_SSH_KEY</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Production</strong> secrets:
|
||||
<ul>
|
||||
<li><code>PROD_DEPLOY_HOST</code></li>
|
||||
<li><code>PROD_DEPLOY_USER</code></li>
|
||||
<li><code>PROD_DEPLOY_PORT</code></li>
|
||||
<li><code>PROD_DEPLOY_PATH</code></li>
|
||||
<li><code>PROD_DEPLOY_SSH_KEY</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<h3>Exact GitHub UI steps</h3>
|
||||
<ol>
|
||||
<li>Open the private repository on GitHub.</li>
|
||||
<li>Open <code>Settings</code>.</li>
|
||||
<li>Open <code>Environments</code> in the left sidebar.</li>
|
||||
<li>Create the environment <code>development</code>.</li>
|
||||
<li>Create the environment <code>production</code>.</li>
|
||||
<li>Open <code>development</code>.</li>
|
||||
<li>Under <code>Environment secrets</code>, add the deployment secrets one by one.</li>
|
||||
<li>Repeat later for <code>production</code>.</li>
|
||||
</ol>
|
||||
<h3>Current test deployment values</h3>
|
||||
<ul>
|
||||
<li>Host: <code>192.168.2.55</code></li>
|
||||
<li>User: <code>root</code></li>
|
||||
<li>Path: <code>/opt/workdock</code></li>
|
||||
<li>URL: <code>http://192.168.2.55:8088</code></li>
|
||||
</ul>
|
||||
<h3>Current development secrets</h3>
|
||||
<ul>
|
||||
<li><code>TEST_DEPLOY_HOST=192.168.2.55</code></li>
|
||||
<li><code>TEST_DEPLOY_USER=root</code></li>
|
||||
<li><code>TEST_DEPLOY_PORT=22</code></li>
|
||||
<li><code>TEST_DEPLOY_PATH=/opt/workdock</code></li>
|
||||
<li><code>TEST_DEPLOY_SSH_KEY=<full private key content></code></li>
|
||||
</ul>
|
||||
<h3>First GitHub Actions test</h3>
|
||||
<ol>
|
||||
<li>Open GitHub Actions.</li>
|
||||
<li>Run the workflow <code>Deploy Test</code> on branch <code>develop</code>.</li>
|
||||
<li>Wait for the SSH upload and deploy steps to finish successfully.</li>
|
||||
<li>Verify <code>http://192.168.2.55:8088/healthz/</code> returns HTTP 200.</li>
|
||||
<li>Then verify the app UI in the browser.</li>
|
||||
</ol>
|
||||
<div class="box">
|
||||
<h3>Current operating model</h3>
|
||||
<ul>
|
||||
<li>Repository model: one private GitHub repository.</li>
|
||||
<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>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="box">
|
||||
<h3>Why deploy is manual right now</h3>
|
||||
<p>The test server is inside the local network and uses a private IP address <code>192.168.2.55</code>. GitHub-hosted runners on the public internet cannot reliably reach that target. Because of that, the correct deployment path today is:</p>
|
||||
<ol>
|
||||
<li>push code to GitHub</li>
|
||||
<li>let GitHub run CI</li>
|
||||
<li>deploy from the Mac on the same LAN</li>
|
||||
</ol>
|
||||
<p>Automatic CD from GitHub becomes appropriate only after moving to a public server or using a self-hosted runner inside the LAN.</p>
|
||||
</div>
|
||||
|
||||
<div class="box">
|
||||
<h3>What to do for normal work</h3>
|
||||
<ol>
|
||||
<li>Start from <code>develop</code>.</li>
|
||||
<li>Do the implementation work.</li>
|
||||
<li>Push to GitHub.</li>
|
||||
<li>Let CI finish.</li>
|
||||
<li>Run the local test deployment helper from the Mac.</li>
|
||||
<li>Verify the updated version in the browser.</li>
|
||||
<li>When the integration line is stable, merge <code>develop</code> into <code>main</code>.</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="box">
|
||||
<h3>One-command test deployment</h3>
|
||||
<p>From the Mac on the same network:</p>
|
||||
<pre><code>git checkout develop
|
||||
./scripts/deploy_test_from_mac.sh</code></pre>
|
||||
<p>This helper script does all of the following:</p>
|
||||
<ol>
|
||||
<li>checks that the current branch is <code>develop</code></li>
|
||||
<li>fast-forwards from <code>origin/develop</code></li>
|
||||
<li>checks that the server env file exists</li>
|
||||
<li>syncs the repository to <code>/opt/workdock</code> with <code>rsync</code></li>
|
||||
<li>preserves server-local env files like <code>.env.test</code> and <code>.env.prod</code></li>
|
||||
<li>runs the remote deployment script</li>
|
||||
<li>waits for the health endpoint</li>
|
||||
<li>prints the deployed commit and branch</li>
|
||||
</ol>
|
||||
</div>
|
||||
|
||||
<div class="box">
|
||||
<h3>Current test server values</h3>
|
||||
<ul>
|
||||
<li>Host: <code>192.168.2.55</code></li>
|
||||
<li>SSH user: <code>root</code></li>
|
||||
<li>Deploy path: <code>/opt/workdock</code></li>
|
||||
<li>Env file: <code>.env.test</code></li>
|
||||
<li>Health URL: <code>http://192.168.2.55:8088/healthz/</code></li>
|
||||
<li>Public app URL: <code>https://workdock.bostame.de/</code></li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="box">
|
||||
<h3>GitHub Actions status</h3>
|
||||
<ul>
|
||||
<li><code>.github/workflows/deploy-test.yml</code> exists, but GitHub-hosted deploy to the LAN server is not the recommended path right now.</li>
|
||||
<li><code>.github/workflows/deploy-prod.yml</code> exists for later production use.</li>
|
||||
<li>The practical use of GitHub today is CI, code review, PRs, and branch history.</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="box">
|
||||
<h3>If the local deploy helper fails</h3>
|
||||
<ol>
|
||||
<li>Check whether <code>/opt/workdock/.env.test</code> still exists on the server.</li>
|
||||
<li>Check SSH access from the Mac:
|
||||
<pre><code>ssh -4 root@192.168.2.55</code></pre>
|
||||
</li>
|
||||
<li>Check server health directly:
|
||||
<pre><code>curl -I http://192.168.2.55:8088/healthz/</code></pre>
|
||||
</li>
|
||||
<li>Check container status:
|
||||
<pre><code>ssh root@192.168.2.55 "cd /opt/workdock && docker compose --env-file .env.test -f docker-compose.prod.yml ps"</code></pre>
|
||||
</li>
|
||||
</ol>
|
||||
</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. This is acceptable for the internal test box only. Production must run with HTTPS and <code>DEBUG=0</code>.
|
||||
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>.
|
||||
</div>
|
||||
|
||||
<h2 id="deploy">15) Deployment</h2>
|
||||
|
||||
Reference in New Issue
Block a user