diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 3c36495..c9ef327 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -7,6 +7,24 @@ - GitHub Actions uploads the repository contents to the server over SSH - the server does not need GitHub access to deploy +## Standard target model for later +When this moves from an internal test setup to a more standard delivery model, the target should be: +1. feature branch +2. CI +3. merge into `develop` +4. staging deploy +5. staging validation +6. merge into `main` +7. production deploy + +Recommended standards for that future state: +- staging and production use separate hosts or clearly separated environments +- staging and production use separate secrets +- production deploys only from `main` +- production runs with HTTPS and `DJANGO_DEBUG=0` +- production deploys require environment protection or approval in GitHub +- rollback is documented and tested + This is intentional. For a private repository, server-side `git clone` adds unnecessary credential management. ## Branch strategy diff --git a/backend/workflows/templates/workflows/developer_handbook.html b/backend/workflows/templates/workflows/developer_handbook.html index 87cf19e..c59248c 100644 --- a/backend/workflows/templates/workflows/developer_handbook.html +++ b/backend/workflows/templates/workflows/developer_handbook.html @@ -366,6 +366,16 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS +
+

What is good enough today vs what is standard later

+ +
+

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:

@@ -377,6 +387,34 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS

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

+
+

Recommended standard CI/CD model

+
    +
  1. Keep one private repository.
    2. +
  2. Use short-lived feature branches from develop.
    3. +
  3. Require CI to pass before merge into develop.
    4. +
  4. Deploy develop to a staging environment.
    5. +
  5. Promote develop into main only after staging validation.
    6. +
  6. Deploy main to production behind HTTPS with DEBUG=0.
    7. +
  7. Protect production with GitHub environment approvals, production secrets, and rollback steps.
    8. +
+

If you want the most standard shape, the long-term target is:

+ 
feature branch -> CI -> develop -> staging deploy -> validate -> main -> production deploy
+
+ +
+

What to change when this becomes a standard deployment

+
    +
  1. Move staging and production onto hosts that GitHub or a self-hosted runner can reach reliably.
    2. +
  2. Keep separate env files and secrets for staging and production.
    3. +
  3. Run production with DJANGO_DEBUG=0, secure cookies, and HTTPS only.
    4. +
  4. Add GitHub environment protection rules for development and production.
    5. +
  5. Use the production deploy path only from main.
    6. +
  6. Add backup verification and health verification as standard post-deploy checks.
    7. +
  7. Later, consider image-based deploys if you want cleaner rollbacks than source-upload deploys.
    8. +
+
+

What to do for normal work

    @@ -391,6 +429,15 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
+
+

Decision guide

+ +
+

One-command test deployment

From the Mac on the same network:

@@ -448,6 +495,17 @@ make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
+
+

Minimal standard checklist for later

+ +
+

If the local deploy helper fails