deploy/README.md

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:

   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:

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 /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 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