diff --git a/backend/workflows/templates/workflows/developer_handbook.html b/backend/workflows/templates/workflows/developer_handbook.html index d72a959..04d5474 100644 --- a/backend/workflows/templates/workflows/developer_handbook.html +++ b/backend/workflows/templates/workflows/developer_handbook.html @@ -287,73 +287,98 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS

14) CI/CD

- -

GitHub Environments

- -

Exact GitHub UI steps

-
    -
  1. Open the private repository on GitHub.
    2. -
  2. Open Settings.
    3. -
  3. Open Environments in the left sidebar.
    4. -
  4. Create the environment development.
    5. -
  5. Create the environment production.
    6. -
  6. Open development.
    7. -
  7. Under Environment secrets, add the deployment secrets one by one.
    8. -
  8. Repeat later for production.
    9. -
-

Current test deployment values

- -

Current development secrets

- -

First GitHub Actions test

-
    -
  1. Open GitHub Actions.
    2. -
  2. Run the workflow Deploy Test on branch develop.
    3. -
  3. Wait for the SSH upload and deploy steps to finish successfully.
    4. -
  4. Verify http://192.168.2.55:8088/healthz/ returns HTTP 200.
    5. -
  5. Then verify the app UI in the browser.
    6. -
+
+

Current operating model

+ +
+ +
+

Why deploy is manual right now

+

The test server is inside the local network and uses a private IP address 192.168.2.55. GitHub-hosted runners on the public internet cannot reliably reach that target. Because of that, the correct deployment path today is:

+
    +
  1. push code to GitHub
    2. +
  2. let GitHub run CI
    3. +
  3. deploy from the Mac on the same LAN
    4. +
+

Automatic CD from GitHub becomes appropriate only after moving to a public server or using a self-hosted runner inside the LAN.

+
+ +
+

What to do for normal work

+
    +
  1. Start from develop.
    2. +
  2. Do the implementation work.
    3. +
  3. Push to GitHub.
    4. +
  4. Let CI finish.
    5. +
  5. Run the local test deployment helper from the Mac.
    6. +
  6. Verify the updated version in the browser.
    7. +
  7. When the integration line is stable, merge develop into main.
    8. +
+
+ +
+

One-command test deployment

+

From the Mac on the same network:

+ 
git checkout develop
+./scripts/deploy_test_from_mac.sh
+

This helper script does all of the following:

+
    +
  1. checks that the current branch is develop
    2. +
  2. fast-forwards from origin/develop
    3. +
  3. checks that the server env file exists
    4. +
  4. syncs the repository to /opt/workdock with rsync
    5. +
  5. preserves server-local env files like .env.test and .env.prod
    6. +
  6. runs the remote deployment script
    7. +
  7. waits for the health endpoint
    8. +
  8. prints the deployed commit and branch
    9. +
+
+ +
+

Current test server values

+ +
+ +
+

GitHub Actions status

+ +
+ +
+

If the local deploy helper fails

+
    +
  1. Check whether /opt/workdock/.env.test still exists on the server.
    2. +
  2. Check SSH access from the Mac: + 
    ssh -4 root@192.168.2.55
    +
    3. +
  3. Check server health directly: + 
    curl -I http://192.168.2.55:8088/healthz/
    +
    4. +
  4. Check container status: + 
    ssh root@192.168.2.55 "cd /opt/workdock && docker compose --env-file .env.test -f docker-compose.prod.yml ps"
    +
    5. +
+
+
- The current LAN test deployment intentionally uses DJANGO_DEBUG=1 in .env.test because the security checks correctly reject insecure cookie settings when DEBUG=0 and the deployment is still plain HTTP. This is acceptable for the internal test box only. Production must run with HTTPS and DEBUG=0. + The current LAN test deployment intentionally uses DJANGO_DEBUG=1 in .env.test because the security checks correctly reject insecure cookie settings when DEBUG=0 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 DEBUG=0.

15) Deployment