feat: implement Phase 6 self-hosting ecosystem

baijum · claude · baijum · commit 3892fc4fab45 · 2026-03-16T04:51:19.000+05:30
Parameterize infrastructure scripts to remove all hardcoded values
(anulectra.com, towlion/platform). Bootstrap script now accepts
ACME_EMAIL, OPS_DOMAIN, and ALERT_REPO as env vars. Fix documentation
to list correct 4 required secrets (not 7). Add critical missing step
to tutorial (pre-clone app on server). Update roadmap status.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/docs/roadmap.md b/docs/roadmap.md
@@ -93,7 +93,7 @@ Enable self-hosting through repository forks.
 
 **Done when:** A person who has never seen the project can fork an app repo, configure 4-5 secrets, run the bootstrap script on a fresh server, push to `main`, and have a working deployment. Tested by someone other than the author.
 
-**Status:** Model is conceptually sound but impractical without bootstrap automation.
+**Status:** Infrastructure parameterized (ACME_EMAIL, OPS_DOMAIN, ALERT_REPO replace all hardcoded values). Documentation corrected (self-hosting.md, tutorial.md list correct 4 secrets, tutorial uses bootstrap script). App-template README updated with deployment secrets and self-hosting links. Awaiting external validation (tested by someone other than the author).
 
 ## Phase 7 — Application Development
 
diff --git a/docs/self-hosting.md b/docs/self-hosting.md
@@ -56,20 +56,17 @@ Fork users must configure these GitHub Actions secrets:
 | Secret | Purpose |
 |---|---|
 | `SERVER_HOST` | Server IP address |
-| `SERVER_USER` | SSH user |
+| `SERVER_USER` | SSH user (typically `deploy`) |
 | `SERVER_SSH_KEY` | SSH private key for deployment |
-| `APP_DOMAIN` | Application domain name |
-| `DATABASE_PASSWORD` | PostgreSQL password |
-| `MINIO_ROOT_USER` | MinIO admin username |
-| `MINIO_ROOT_PASSWORD` | MinIO admin password |
-| `EMAIL_API_KEY` | Transactional email API key |
+| `APP_DOMAIN` | Application domain name (e.g., `app.example.com`) |
+
+> **Note:** Database and storage credentials are auto-generated by the bootstrap script on the server. They are not GitHub secrets.
 
 Optional secrets:
 
 | Secret | Purpose |
 |---|---|
-| `SENTRY_DSN` | Error tracking |
-| `REDIS_PASSWORD` | Redis authentication |
+| `PREVIEW_DOMAIN` | Base domain for preview environments (e.g., `example.com`) |
 
 ## Bootstrap Process
 
@@ -87,21 +84,46 @@ To deploy an application from a fork:
 The repository includes a single bootstrap script that transforms a fresh Debian 12 server into a ready-to-deploy platform:
 
 ```bash
-sudo bash infrastructure/bootstrap-server.sh
+sudo ACME_EMAIL=you@example.com OPS_DOMAIN=ops.example.com bash infrastructure/bootstrap-server.sh
 ```
 
 The script is idempotent — safe to re-run on an already-bootstrapped server. It performs:
 
-- System packages (git, curl, ufw)
+- System packages (git, curl, ufw, vnstat, unattended-upgrades)
 - Firewall configuration (ports 22, 80, 443)
 - Docker and Compose plugin installation
 - `deploy` user creation with SSH directory
-- Directory structure (`/data/postgres`, `/data/redis`, `/data/minio`, `/data/caddy`, `/opt/apps`, `/opt/platform`)
+- Directory structure (`/data/*`, `/opt/apps`, `/opt/platform`)
 - Docker network (`towlion`) for cross-container communication
-- Credential generation (PostgreSQL and MinIO passwords in `/opt/platform/.env`)
+- Credential generation (PostgreSQL, MinIO, and Grafana passwords in `/opt/platform/.env`)
 - Platform Caddyfile with per-app import pattern
-- Platform `docker-compose.yml` (PostgreSQL 16, Redis 7, MinIO, Caddy 2)
+- Platform `docker-compose.yml` (PostgreSQL 16, Redis 7, MinIO, Caddy 2, Loki 3.0, Promtail 3.0, Grafana 11.0)
 - Service startup and verification
+- Infrastructure scripts and cron jobs (backups, alerts, image updates)
+
+### Post-Bootstrap Verification
+
+After bootstrapping, run the verification script to confirm everything is working:
+
+```bash
+bash infrastructure/verify-server.sh
+```
+
+This performs a read-only check of all services, directories, and firewall rules.
+
+### Per-App Credentials
+
+For each application, provision isolated database and storage credentials:
+
+```bash
+bash /opt/platform/infrastructure/create-app-credentials.sh <app-name>
+```
+
+This creates a dedicated PostgreSQL user and MinIO bucket. Credentials are written to `/opt/platform/credentials/<app-name>.env` and automatically picked up by the deploy workflow.
+
+### Monitoring (Optional)
+
+If you set `OPS_DOMAIN` during bootstrap (or add it to `/opt/platform/.env`), Grafana is accessible at `https://OPS_DOMAIN`. The default admin credentials are in `/opt/platform/.env`. Configure DNS for the ops domain the same way as app domains.
 
 ## DNS Configuration
 
diff --git a/docs/server-contract.md b/docs/server-contract.md
@@ -7,7 +7,7 @@ This document defines the contract between the platform infrastructure (bootstra
 ```
 /opt/platform/                          # Platform root (created by bootstrap-server.sh)
   docker-compose.yml                    # Platform services (postgres, redis, minio, caddy, loki, promtail, grafana)
-  .env                                  # Platform credentials (POSTGRES_PASSWORD, MINIO_ROOT_*, GRAFANA_ADMIN_PASSWORD, ACME_EMAIL)
+  .env                                  # Platform credentials (POSTGRES_PASSWORD, MINIO_ROOT_*, GRAFANA_ADMIN_PASSWORD, ACME_EMAIL, OPS_DOMAIN, ALERT_REPO)
   .bootstrapped                         # Timestamp marker from last bootstrap run
   Caddyfile                             # Global Caddyfile — imports /etc/caddy/apps/*.caddy
   caddy-apps/                           # Per-app Caddyfile fragments (written by deploy/preview workflows)
diff --git a/docs/tutorial.md b/docs/tutorial.md
@@ -51,51 +51,61 @@ You should see a shell prompt. If this works, you are ready to bootstrap.
 
 ## Step 3: Bootstrap the server
 
-SSH into your server and install Docker:
+SSH into your server as root and run the bootstrap script. This installs Docker, creates the `deploy` user, starts all platform services, and generates credentials:
 
 ```bash
-ssh deploy@YOUR_SERVER_IP
+ssh root@YOUR_SERVER_IP
+git clone https://github.com/towlion/platform.git /tmp/platform
+sudo ACME_EMAIL=you@example.com bash /tmp/platform/infrastructure/bootstrap-server.sh
 ```
 
-Install Docker using the official convenience script:
+!!! tip
+    Set `OPS_DOMAIN=ops.example.com` to also enable the Grafana monitoring dashboard:
+    ```bash
+    sudo ACME_EMAIL=you@example.com OPS_DOMAIN=ops.example.com bash /tmp/platform/infrastructure/bootstrap-server.sh
+    ```
+
+Verify the bootstrap was successful:
 
 ```bash
-curl -fsSL https://get.docker.com | sudo sh
-sudo usermod -aG docker $USER
+bash /tmp/platform/infrastructure/verify-server.sh
 ```
 
-!!! warning
-    Log out and back in after adding yourself to the `docker` group, or the next commands will fail with a permission error.
+All checks should pass. The script creates:
+
+```
+/data/              # Persistent data (postgres, redis, minio, caddy, loki, grafana)
+/opt/platform/      # Platform services and config
+/opt/apps/          # Application deployments
+```
+
+## Step 3.5: Clone your app on the server
+
+The deploy workflow runs `git pull` (not `git clone`), so the app must be pre-cloned on the server. SSH in as the `deploy` user:
 
 ```bash
-exit
 ssh deploy@YOUR_SERVER_IP
+cd /opt/apps
+git clone git@github.com:YOUR_USERNAME/app-template.git my-app
+cd my-app
 ```
 
-Verify Docker is working:
+Provision per-app database and storage credentials:
 
 ```bash
-docker run --rm hello-world
+sudo /opt/platform/infrastructure/create-app-credentials.sh my-app
 ```
 
-You should see `Hello from Docker!` in the output.
-
-Create the data directory structure:
+Create the deploy environment file from the template:
 
 ```bash
-sudo mkdir -p /data/{postgres,redis,minio,caddy}
-sudo chown -R $USER:$USER /data
+cp deploy/env.template deploy/.env
 ```
 
-This is where persistent data lives across deployments. The directory layout:
+The deploy workflow will auto-update `deploy/.env` with the correct credentials on the next push.
 
-```
-/data/
-  postgres/    # Database files
-  redis/       # Cache and queue data
-  minio/       # Object storage
-  caddy/       # TLS certificates and config
-```
+!!! warning
+    The `deploy` user needs SSH access to your GitHub repo to `git pull`. Add the deploy user's public key (`/home/deploy/.ssh/id_ed25519.pub`) as a deploy key on your GitHub repository, or use HTTPS cloning with a personal access token.
 
 ## Step 4: Configure DNS
 
@@ -139,9 +149,10 @@ In your forked repository on GitHub, go to **Settings > Secrets and variables >
 | `SERVER_USER` | `deploy` | SSH username on the server |
 | `SERVER_SSH_KEY` | *(private key contents)* | SSH private key for deployment |
 | `APP_DOMAIN` | `app.example.com` | Domain pointing to your server |
-| `DATABASE_PASSWORD` | *(strong password)* | PostgreSQL password |
-| `MINIO_ROOT_USER` | `minio-admin` | MinIO admin username |
-| `MINIO_ROOT_PASSWORD` | *(strong password)* | MinIO admin password |
+
+> **Note:** Database and storage credentials are auto-generated by the bootstrap script on the server. You do not need to create them as GitHub secrets.
+
+Optionally, add `PREVIEW_DOMAIN` (e.g., `example.com`) to enable preview environments for pull requests.
 
 ### Generate a deploy SSH key
 
diff --git a/infrastructure/bootstrap-server.sh b/infrastructure/bootstrap-server.sh
@@ -13,6 +13,11 @@ error() { echo -e "${RED}[ERROR]${NC} $1"; exit 1; }
 
 MARKER="/opt/platform/.bootstrapped"
 
+# Optional environment variables:
+#   ACME_EMAIL   - Email for Let's Encrypt TLS certificates (required for production)
+#   OPS_DOMAIN   - Domain for Grafana dashboard (e.g., ops.example.com)
+#   ALERT_REPO   - GitHub repo for alert issues (e.g., youruser/platform)
+
 # --- Preflight ---
 
 if [[ $EUID -ne 0 ]]; then
@@ -177,12 +182,18 @@ POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
 MINIO_ROOT_USER=${MINIO_ROOT_USER}
 MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD}
 GRAFANA_ADMIN_PASSWORD=${GRAFANA_ADMIN_PASSWORD}
-ACME_EMAIL=admin@localhost
+ACME_EMAIL=${ACME_EMAIL:-admin@localhost}
+OPS_DOMAIN=${OPS_DOMAIN:-localhost}
+ALERT_REPO=${ALERT_REPO:-}
 EOF
 
   chmod 600 "$ENV_FILE"
   chown deploy:deploy "$ENV_FILE"
   info "Credentials generated and written to $ENV_FILE"
+
+  if [[ "${ACME_EMAIL:-admin@localhost}" == "admin@localhost" ]]; then
+    warn "ACME_EMAIL is admin@localhost — TLS certificates will fail. Re-run with ACME_EMAIL=you@example.com"
+  fi
 fi
 
 # --- Caddyfile ---
@@ -400,7 +411,7 @@ else
       "gridPos": { "h": 4, "w": 24, "x": 0, "y": 20 },
       "options": {
         "mode": "markdown",
-        "content": "## Towlion Platform Overview\n\nThis dashboard shows logs from all containers on the platform.\n\n- **Log Stream**: All container logs (filter by service label)\n- **Error Rate**: Count of ERROR lines per service over 5-minute windows\n- **Container Logs by App**: Select an app from the dropdown to filter logs\n\nAlerts are managed by `check-alerts.sh` (cron every 5 min) and create GitHub Issues on the `towlion/platform` repo."
+        "content": "## Towlion Platform Overview\n\nThis dashboard shows logs from all containers on the platform.\n\n- **Log Stream**: All container logs (filter by service label)\n- **Error Rate**: Count of ERROR lines per service over 5-minute windows\n- **Container Logs by App**: Select an app from the dropdown to filter logs\n\nAlerts are managed by `check-alerts.sh` (cron every 5 min) and create GitHub Issues when ALERT_REPO is configured."
       }
     }
   ],
@@ -435,15 +446,17 @@ fi
 OPS_CADDY="/opt/platform/caddy-apps/ops.caddy"
 if [[ -f "$OPS_CADDY" ]]; then
   info "Grafana Caddy route already exists"
-else
-  cat > "$OPS_CADDY" <<'EOF'
-ops.anulectra.com {
+elif [[ -n "${OPS_DOMAIN:-}" ]]; then
+  cat > "$OPS_CADDY" <<EOF
+${OPS_DOMAIN} {
     reverse_proxy grafana:3000
 }
 EOF
 
   chown deploy:deploy "$OPS_CADDY"
   info "Grafana Caddy route created at $OPS_CADDY"
+else
+  info "OPS_DOMAIN not set — skipping Grafana Caddy route (set OPS_DOMAIN to enable)"
 fi
 
 # --- Platform Compose File ---
@@ -606,7 +619,7 @@ services:
     environment:
       GF_SECURITY_ADMIN_USER: ${GRAFANA_ADMIN_USER:-admin}
       GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD}
-      GF_SERVER_ROOT_URL: https://ops.anulectra.com
+      GF_SERVER_ROOT_URL: https://${OPS_DOMAIN:-localhost}
     volumes:
       - /data/grafana:/var/lib/grafana
       - ./grafana/provisioning:/etc/grafana/provisioning:ro
@@ -687,7 +700,7 @@ else
 fi
 
 # Alert check every 5 minutes
-ALERT_CRON="*/5 * * * * /opt/platform/infrastructure/check-alerts.sh >> /var/log/towlion-alerts.log 2>&1"
+ALERT_CRON="*/5 * * * * . /opt/platform/.env && /opt/platform/infrastructure/check-alerts.sh >> /var/log/towlion-alerts.log 2>&1"
 if echo "$DEPLOY_CRON" | grep -q "check-alerts"; then
   info "Alert cron job already exists"
 else
@@ -746,10 +759,26 @@ echo
 echo "Next steps:"
 echo "  1. Add your SSH public key to /home/deploy/.ssh/authorized_keys"
 echo "  2. Configure DNS — point your domain to this server's IP"
-echo "  3. Update ACME_EMAIL in $ENV_FILE to a real email for TLS certificates"
-echo "  4. Set GitHub Actions secrets on your app repo:"
+echo "  3. Set GitHub Actions secrets on your app repo:"
 echo "     SERVER_HOST, SERVER_USER (deploy), SERVER_SSH_KEY, APP_DOMAIN"
-echo "  5. Run create-app-credentials.sh <app-name> for per-app credentials"
-echo "  6. Create app dir, clone repo, create deploy/.env from template"
-echo "  7. Push to main — deployment runs automatically"
-echo "  8. Set GITHUB_TOKEN in $ENV_FILE for alert issue creation (optional)"
+echo "  4. Run create-app-credentials.sh <app-name> for per-app credentials"
+echo "  5. Clone app repo to /opt/apps/<name>, create deploy/.env from template"
+echo "  6. Push to main — deployment runs automatically"
+
+if [[ "${ACME_EMAIL:-admin@localhost}" == "admin@localhost" ]]; then
+  echo
+  echo -e "${YELLOW}  ACTION REQUIRED: Set ACME_EMAIL in $ENV_FILE to a real email for TLS certificates.${NC}"
+  echo "  Or re-run: sudo ACME_EMAIL=you@example.com bash bootstrap-server.sh"
+fi
+
+if [[ "${OPS_DOMAIN:-localhost}" == "localhost" ]]; then
+  echo
+  echo -e "${YELLOW}  OPTIONAL: Set OPS_DOMAIN in $ENV_FILE for Grafana dashboard access.${NC}"
+  echo "  Or re-run: sudo OPS_DOMAIN=ops.example.com bash bootstrap-server.sh"
+fi
+
+if [[ -z "${ALERT_REPO:-}" ]]; then
+  echo
+  echo -e "${YELLOW}  OPTIONAL: Set ALERT_REPO in $ENV_FILE (e.g., youruser/platform) for GitHub issue alerts.${NC}"
+  echo "  Also set GITHUB_TOKEN for issue creation."
+fi
diff --git a/infrastructure/check-alerts.sh b/infrastructure/check-alerts.sh
@@ -8,8 +8,11 @@ set -euo pipefail
 TIMESTAMP=$(date '+%Y-%m-%d %H:%M:%S')
 ALERTS=()
 
-# Check if GITHUB_TOKEN is set (required for issue creation)
-if [[ -z "${GITHUB_TOKEN:-}" ]]; then
+# Check if ALERT_REPO and GITHUB_TOKEN are set (required for issue creation)
+if [[ -z "${ALERT_REPO:-}" ]]; then
+    echo "[$TIMESTAMP] WARNING: ALERT_REPO not set — alerts will be logged but not posted to GitHub"
+    CREATE_ISSUES=false
+elif [[ -z "${GITHUB_TOKEN:-}" ]]; then
     echo "[$TIMESTAMP] WARNING: GITHUB_TOKEN not set, alerts will only be logged (not created as issues)"
     CREATE_ISSUES=false
 else
@@ -55,7 +58,7 @@ if [[ ${#ALERTS[@]} -gt 0 ]]; then
 
         if [[ "$CREATE_ISSUES" == true ]]; then
             # Check if issue already exists (dedup)
-            EXISTING=$(gh issue list --repo towlion/platform \
+            EXISTING=$(gh issue list --repo "${ALERT_REPO}" \
                 --search "Alert: $alert in:title" \
                 --state open \
                 --limit 1 \
@@ -85,7 +88,7 @@ This issue was automatically created by \`infrastructure/check-alerts.sh\`."
 
                 echo "[$TIMESTAMP] Creating issue..."
                 gh issue create \
-                    --repo towlion/platform \
+                    --repo "${ALERT_REPO}" \
                     --title "$ISSUE_TITLE" \
                     --body "$ISSUE_BODY" \
                     --label "alert" || echo "[$TIMESTAMP] Failed to create issue"
