Spaces:
Runtime error
Runtime error
| # 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` | |