deploy/README.md

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:

   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 /opt/notestack/deploy/update.sh

Useful commands (from /opt/notestack/deploy)

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.