Deployment & Migrations
Deployment involves the Next.js app, the FastAPI agent service, and the Supabase project. The database schema is applied through numbered SQL migrations; backups and restore are provided by the managed database platform, with an in-app organization data export.
#Purpose
#Architecture
The Next.js app and the agent service are deployed as separate runtimes (the agent service ships with a Dockerfile). Both connect to the Supabase project, which hosts PostgreSQL, auth, and storage.
Schema changes are delivered as forward, numbered SQL migrations applied to the database. Backup and point-in-time restore are handled by the managed database platform; organizations can also export their own data from Settings.
#How it works
Provision Supabase
Apply migrations
Deploy app & agent
Schedule jobs
#Implementation notes
- Migrations are numbered (001 onward) and applied in sequence.
- The agent service requires its shared secret and AI access to be configured.
- Managed platform backups cover the database; org export covers tenant self-service copies.
#Limitations
Known limitations
- No custom in-app backup/restore tooling beyond organization export; database backups are platform-managed.
- Migrations are forward-only by convention.
#Security considerations
Security
- Keep production secrets out of source control.
- Restrict who can apply migrations and access the service-role key.
- Verify environment parity (encryption keys, agent secret) across services.
#Best practices
- Apply migrations in order and test on a staging database.
- Keep the agent service and app secrets in sync.
- Verify health endpoints after each deploy.
#Related documentation
What migrations build.
Required variables.
Post-deploy checks.
Still need help?
Can’t find what you’re looking for? The DevSphere OS team is happy to help.