Add deployment configuration files for DigitalOcean Droplet setup

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,62 @@
+# Deploying the backend to a DigitalOcean Droplet
+
+One Droplet runs the API, the job worker and, optionally, the video renderer. HTTPS comes from the reverse
+proxy already on the Droplet (Nginx, see nginx-notestack.conf), or from the bundled Caddy (`CADDY=1`) on a
+Droplet with nothing else on ports 80 and 443.
+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`.
+
+## Sharing the Droplet with other backends (Nginx)
+
+The API listens on `127.0.0.1:8010` only (`API_PORT`). Point Nginx at it:
+
+```bash
+sudo cp /opt/notestack/deploy/nginx-notestack.conf /etc/nginx/sites-available/notestack
+sudo ln -s /etc/nginx/sites-available/notestack /etc/nginx/sites-enabled/notestack
+sudo nginx -t && sudo systemctl reload nginx
+sudo certbot --nginx -d api.notestack.ai
+```
+
+## 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** are not applied automatically. After an update that adds one, run from `deploy/`:
+  `docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm api alembic upgrade head`

deploy/docker-compose.prod.yml

@@ -0,0 +1,64 @@
+# 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
+# The API listens on 127.0.0.1:API_PORT (default 8010) for the reverse proxy already on this host (Nginx,
+# Caddy...). On a Droplet with nothing else on ports 80/443, start the bundled Caddy with --profile caddy.
+
+services:
+  api:
+    build: ../backend
+    restart: unless-stopped
+    env_file: .env.prod
+    # Migrations are NOT applied on start. Run them by hand: docker compose --env-file .env.prod -f docker-compose.prod.yml run --rm api alembic upgrade head
+    # Proxy headers let the API see the real client IP and https scheme behind Caddy.
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'
+    ports:
+      - "127.0.0.1:${API_PORT:-8010}:8000" # local only: the host proxy forwards API_DOMAIN here
+    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: # only on a Droplet with no other web server: --profile caddy
+    image: caddy:2
+    restart: unless-stopped
+    profiles: ["caddy"]
+    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,80 @@
+# 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
+# Local port the host reverse proxy (Nginx) forwards API_DOMAIN to. Change it if 8010 is taken.
+API_PORT=8010
+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
+# Sharing a bucket with other apps? Keep Notestack in its own folder:
+R2_PREFIX=
+
+# ---- AI
+LLM_API_KEY=<z.ai key>
+ELEVENLABS_API_KEY=<elevenlabs key>
+TYPESAFE_API_KEY=
+FIRECRAWL_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
+# Stripe. Checkout, the customer portal and webhooks. Prices are found or created by lookup key
+# (notestack_<plan>_<cycle>) from backend/app/services/plans.py; set STRIPE_PRICE_* to pin existing ones.
+# Webhook endpoint: {API_URL}/api/billing/webhook with events checkout.session.completed,
+# checkout.session.async_payment_succeeded, checkout.session.async_payment_failed,
+# customer.subscription.created, customer.subscription.updated, customer.subscription.deleted,
+# customer.subscription.paused, customer.subscription.resumed, invoice.paid, invoice.payment_failed,
+# invoice.payment_action_required, charge.dispute.created.
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PRICE_WRITER_MONTHLY=
+STRIPE_PRICE_WRITER_ANNUAL=
+STRIPE_PRICE_STUDIO_MONTHLY=
+STRIPE_PRICE_STUDIO_ANNUAL=

deploy/huggingface/Dockerfile

@@ -0,0 +1,21 @@
+# Hugging Face Spaces image, built from the repo root (the Space holds the whole repo).
+# Upload this file to the Space root as `Dockerfile`. One container, non-root uid 1000, port 7860;
+# the worker runs inside the API process.
+FROM python:3.12-slim
+
+RUN useradd -m -u 1000 user
+WORKDIR /app
+ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 \
+    ENV=production \
+    RUN_WORKER_IN_API=true \
+    CORPUS_CACHE_DIR=/app/.corpus-cache \
+    LOCAL_STORAGE_DIR=/app/.storage
+
+COPY backend/requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY --chown=user backend/ .
+RUN rm -f .env
+USER user
+
+EXPOSE 7860
+CMD ["sh", "-c", "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 7860 --proxy-headers --forwarded-allow-ips='*'"]

deploy/nginx-notestack.conf

@@ -0,0 +1,31 @@
+# Nginx site for the Notestack API on a Droplet that already runs other backends.
+#   sudo cp /opt/notestack/deploy/nginx-notestack.conf /etc/nginx/sites-available/notestack
+#   sudo ln -s /etc/nginx/sites-available/notestack /etc/nginx/sites-enabled/notestack
+#   sudo nginx -t && sudo systemctl reload nginx
+#   sudo certbot --nginx -d api.notestack.ai        # adds HTTPS and the 443 server block
+# The API container listens on 127.0.0.1:8010 (API_PORT in deploy/.env.prod).
+
+server {
+    listen 80;
+    listen [::]:80;
+    server_name api.notestack.ai;
+
+    # Voice samples, PDFs and other uploads.
+    client_max_body_size 220m;
+
+    location / {
+        proxy_pass http://127.0.0.1:8010;
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Connection "";
+
+        # Job progress and chat are server sent events: stream them, do not buffer or time out early.
+        proxy_buffering off;
+        proxy_cache off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+    }
+}

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,46 @@
+#!/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
+#   CADDY=1  bash /opt/notestack/deploy/update.sh   # bundled Caddy (only if nothing else uses ports 80/443)
+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)
+[ "${CADDY:-0}" = "1" ] && profile+=(--profile caddy)
+
+docker compose --env-file .env.prod -f docker-compose.prod.yml "${profile[@]}" up -d --build --remove-orphans
+docker image prune -f >/dev/null
+
+port=$(grep -E '^API_PORT=' .env.prod | cut -d= -f2)
+port=${port:-8010}
+echo "==> Waiting for the API on 127.0.0.1:$port"
+for _ in $(seq 1 30); do
+  curl -fsS "http://127.0.0.1:$port/api/health" >/dev/null 2>&1 && break
+  sleep 4
+done
+curl -fsS "http://127.0.0.1:$port/api/health" || { echo "API not up. Logs: cd deploy && docker compose --env-file .env.prod -f docker-compose.prod.yml logs -f api"; exit 1; }
+echo
+
+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