launching

deploy/.gitattributes

@@ -0,0 +1,4 @@
+*.sh text eol=lf
+Caddyfile text eol=lf
+*.yml text eol=lf
+env.prod.example text eol=lf

deploy/Caddyfile

@@ -0,0 +1,21 @@
+{
+	email {$ACME_EMAIL}
+}
+
+# HTTPS certificates are issued and renewed automatically for API_DOMAIN (set in .env.prod).
+{$API_DOMAIN} {
+	encode zstd gzip
+
+	reverse_proxy api:8000 {
+		# Stream job progress and chat (server sent events) instead of buffering them.
+		flush_interval -1
+		transport http {
+			read_timeout 0
+		}
+	}
+
+	# Uploads (voice samples, files) can be large.
+	request_body {
+		max_size 220MB
+	}
+}

deploy/README.md

@@ -0,0 +1,48 @@
+# Deploying the backend to a DigitalOcean Droplet
+
+One Droplet runs the API, the job worker, Caddy (automatic HTTPS) and, optionally, the video renderer.
+The database is Neon. The frontend is on Cloudflare Pages.
+
+## First time
+
+1. **Droplet**: Ubuntu 24.04, 2 GB RAM for API + worker, 4 GB if you also run the renderer. Add your SSH key.
+2. **DNS**: in Cloudflare, add an `A` record `api` pointing to the Droplet IP, **DNS only (grey cloud)** so long
+   running progress streams are not cut at 100 seconds.
+3. **Neon**: Dashboard > Connect, turn **Connection pooling off** (host without `-pooler`), copy the string and
+   change `postgresql://` to `postgresql+psycopg://`.
+4. On the Droplet:
+   ```bash
+   git clone https://github.com/FireBird-Technologies/NotestackAI.git /opt/notestack
+   bash /opt/notestack/deploy/setup.sh        # installs Docker, firewall, swap, creates deploy/.env.prod
+   nano /opt/notestack/deploy/.env.prod       # fill in every <...> value
+   bash /opt/notestack/deploy/update.sh       # builds, starts, waits for https://API_DOMAIN/api/health
+   ```
+   Add `RENDER=1` before `update.sh` to also run the video renderer.
+5. **Frontend**: in Cloudflare Pages set `VITE_API_URL=https://api.notestack.ai`, then retry the deployment.
+6. **Google OAuth client**: redirect URI `https://api.notestack.ai/api/auth/google/callback`, JavaScript origin
+   `https://notestackai.pages.dev`.
+
+## Every update
+
+```bash
+bash /opt/notestack/deploy/update.sh
+```
+
+## Useful commands (from /opt/notestack/deploy)
+
+```bash
+docker compose --env-file .env.prod -f docker-compose.prod.yml ps
+docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f api worker
+docker compose --env-file .env.prod -f docker-compose.prod.yml restart worker
+```
+
+## Notes
+
+- **Why the direct Neon URL**: the worker uses Postgres advisory locks for its scheduled tasks, which do not
+  work through Neon's transaction pooler. Two processes need only a handful of connections.
+- **Neon compute hours**: the worker polls for jobs every `WORKER_POLL_SECONDS`, so Neon's compute stays awake.
+  That is roughly 720 compute hours a month, beyond the free tier; use a paid Neon plan in production.
+- **Files**: with `STORAGE_BACKEND=local` uploads and generated media live in the `appdata` Docker volume on the
+  Droplet (covered by Droplet backups). Switch to Cloudflare R2 before real traffic if you want them to survive
+  losing the Droplet.
+- **Migrations** run automatically every time the API container starts.

deploy/docker-compose.prod.yml

@@ -0,0 +1,62 @@
+# Production stack for a single DigitalOcean Droplet. The database is Neon (DATABASE_URL in .env.prod).
+#   cd /opt/notestack/deploy && docker compose --env-file .env.prod -f docker-compose.prod.yml up -d --build
+# Caddy terminates HTTPS for API_DOMAIN and proxies to the API; the worker and renderer are internal.
+
+services:
+  api:
+    build: ../backend
+    restart: unless-stopped
+    env_file: .env.prod
+    # Migrations run against Neon on every start (no-op when up to date). Proxy headers let the API see the
+    # real client IP and https scheme behind Caddy.
+    command: >
+      sh -c "alembic upgrade head &&
+             uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'"
+    volumes:
+      - appdata:/data
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/api/health')"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 40s
+
+  worker:
+    build: ../backend
+    restart: unless-stopped
+    env_file: .env.prod
+    command: python -m app.worker
+    volumes:
+      - appdata:/data # same volume as the API, so both see the same stored files and corpus cache
+    depends_on:
+      api:
+        condition: service_healthy # the API has applied migrations by the time it is healthy
+
+  renderer:
+    build: ../renderer
+    restart: unless-stopped
+    environment:
+      INTERNAL_TOKEN: ${INTERNAL_TOKEN} # must match the API's
+    profiles: ["render"] # optional: start with --profile render (needs about 2 GB of free RAM)
+
+  caddy:
+    image: caddy:2
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    environment: # only what the Caddyfile needs, not the app secrets
+      API_DOMAIN: ${API_DOMAIN}
+      ACME_EMAIL: ${ACME_EMAIL}
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    depends_on:
+      - api
+
+volumes:
+  appdata: {}
+  caddy_data: {}
+  caddy_config: {}

deploy/env.prod.example

@@ -0,0 +1,62 @@
+# Copy to deploy/.env.prod on the Droplet (git ignores .env.prod) and fill in every <...> value.
+# Generate secrets with: openssl rand -hex 32
+
+# ---- Domains
+API_DOMAIN=api.notestack.ai
+ACME_EMAIL=arslan@firebird-technologies.com
+ENV=production
+API_URL=https://api.notestack.ai
+FRONTEND_URL=https://notestackai.pages.dev
+CORS_ORIGINS=https://notestackai.pages.dev
+
+# ---- Neon Postgres
+# In Neon: Dashboard > Connect. Pick the DIRECT connection (turn "Connection pooling" off: the host must NOT
+# contain "-pooler"), then change the scheme from postgresql:// to postgresql+psycopg://
+DATABASE_URL=postgresql+psycopg://<user>:<password>@<ep-xxxx>.<region>.aws.neon.tech/<db>?sslmode=require
+# The worker checks for jobs every WORKER_POLL_SECONDS, which keeps Neon's compute awake. Raise it to cut
+# compute hours (jobs then start a few seconds later).
+WORKER_POLL_SECONDS=3
+WORKER_CONCURRENCY=3
+RUN_WORKER_IN_API=false
+
+# ---- Secrets (new values for production, never reuse local ones)
+JWT_SECRET=<openssl rand -hex 32>
+INTERNAL_TOKEN=<openssl rand -hex 32>
+UNSUBSCRIBE_SECRET=<openssl rand -hex 32>
+
+# ---- Google sign in (add https://api.notestack.ai/api/auth/google/callback to the OAuth client)
+GOOGLE_CLIENT_ID=<client id>
+GOOGLE_CLIENT_SECRET=<client secret>
+GOOGLE_REDIRECT_URI=https://api.notestack.ai/api/auth/google/callback
+
+# ---- Email
+EMAIL_PROVIDER=resend
+RESEND_API_KEY=<resend key>
+FROM_EMAIL=Notestack <hello@notestack.ai>
+ALERTS_EMAIL=arslan@firebird-technologies.com
+
+# ---- Files. Local disk on the Droplet (kept in the appdata Docker volume, backed up with the Droplet).
+# For R2 instead: set STORAGE_BACKEND=r2 and fill the R2_* values.
+STORAGE_BACKEND=local
+LOCAL_STORAGE_DIR=/data/storage
+CORPUS_CACHE_DIR=/data/corpus
+R2_ACCOUNT_ID=
+R2_ACCESS_KEY_ID=
+R2_SECRET_ACCESS_KEY=
+R2_BUCKET=notestack-assets
+
+# ---- AI
+LLM_API_KEY=<z.ai key>
+ELEVENLABS_API_KEY=<elevenlabs key>
+TYPESAFE_API_KEY=
+
+# ---- Renderer (only used when started with --profile render)
+RENDERER_URL=http://renderer:3100
+
+# ---- Social publishing (optional). Redirect URIs: https://api.notestack.ai/api/social/{x,linkedin}/callback
+X_CLIENT_ID=
+X_CLIENT_SECRET=
+LINKEDIN_CLIENT_ID=
+LINKEDIN_CLIENT_SECRET=
+
+BILLING_ENABLED=false

deploy/setup.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# One time setup for a fresh Ubuntu 24.04 Droplet. Run as root:
+#   git clone https://github.com/FireBird-Technologies/NotestackAI.git /opt/notestack
+#   bash /opt/notestack/deploy/setup.sh
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+echo "==> Installing Docker"
+if ! command -v docker >/dev/null; then
+  curl -fsSL https://get.docker.com | sh
+fi
+
+echo "==> Firewall: SSH, HTTP, HTTPS only"
+ufw allow OpenSSH
+ufw allow 80/tcp
+ufw allow 443/tcp
+ufw allow 443/udp
+ufw --force enable
+
+echo "==> Swap (helps builds and the renderer on small Droplets)"
+if [ ! -f /swapfile ]; then
+  fallocate -l 2G /swapfile
+  chmod 600 /swapfile
+  mkswap /swapfile
+  swapon /swapfile
+  echo '/swapfile none swap sw 0 0' >> /etc/fstab
+fi
+
+if [ ! -f .env.prod ]; then
+  cp env.prod.example .env.prod
+  chmod 600 .env.prod
+  echo
+  echo "Created deploy/.env.prod. Fill in every <...> value, then run: bash deploy/update.sh"
+  exit 0
+fi
+
+echo "==> .env.prod exists; starting the stack"
+bash ./update.sh

deploy/update.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Deploy the latest code: pull, rebuild, restart, then check health.
+#   bash /opt/notestack/deploy/update.sh            # API, worker, Caddy
+#   RENDER=1 bash /opt/notestack/deploy/update.sh   # also the video renderer
+set -euo pipefail
+
+cd "$(dirname "$0")"
+git -C .. pull --ff-only
+
+# Placeholders look like =<...> or <user>/<password> inside DATABASE_URL (FROM_EMAIL's <address> is fine).
+if grep -qE '=<|<(user|password|ep-xxxx|region|db)>' .env.prod; then
+  echo "deploy/.env.prod still has <placeholders>; fill them in first."
+  exit 1
+fi
+
+profile=()
+[ "${RENDER:-0}" = "1" ] && profile=(--profile render)
+
+docker compose --env-file .env.prod -f docker-compose.prod.yml "${profile[@]}" up -d --build --remove-orphans
+docker image prune -f >/dev/null
+
+domain=$(grep -E '^API_DOMAIN=' .env.prod | cut -d= -f2)
+echo "==> Waiting for https://$domain/api/health"
+for _ in $(seq 1 30); do
+  if curl -fsS "https://$domain/api/health" >/dev/null 2>&1; then
+    curl -fsS "https://$domain/api/health"
+    echo
+    echo "==> Live."
+    exit 0
+  fi
+  sleep 4
+done
+echo "Health check did not pass yet. Logs: cd deploy && docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f api"
+exit 1