cp .env.example .env.local
# Configure keys.
docker compose up --build -d
docker compose ps
make healthCompose builds production-mode images, waits for PostgreSQL, checks FastAPI
health, and then starts Next.js. PostgreSQL data remains in the named pgdata
volume after docker compose down.
To remove the database intentionally:
docker compose down --volumesThis is destructive and is not part of make clean.
| Variable | Required | Notes |
|---|---|---|
GEMINI_API_KEY |
Yes* | Primary generation key |
GEMINI_API_KEYS |
No | JSON list for key rotation; can satisfy * |
GEMINI_MODEL |
No | Defaults to the configured Gemini flash model |
SECRET_KEY |
Yes | Use a long random value; signs JWTs |
DATABASE_URL_ASYNC |
Yes | SQLAlchemy async PostgreSQL DSN |
DATABASE_URL |
No | Reserved sync-compatible DSN |
NEXT_PUBLIC_API_URL |
Yes | Browser-visible API origin, set at frontend build |
DEBUG |
No | SQL logging and development diagnostics |
For a non-local domain, add its origin to allowed_origins in backend settings
and build the frontend with the public API URL.
make ps
make health
docker compose logs -f backend
docker compose logs -f frontend
docker compose logs -f dbThe backend health check probes /health; the frontend health check probes /.
Generation progress and failures are persisted in plan_generation_jobs.
- A normal restart recovers queued/running generation jobs.
- Completed agent state is checkpointed after stage updates.
- Cancellation sets a database flag and completes safely between stages.
- Resume is accepted only for
failedorcancelledjobs.
Because workers currently live inside the API process, run one backend replica. Horizontal scaling requires a shared job queue to prevent duplicate execution.
Before any public deployment:
- Rotate every Gemini key ever placed in a tracked file, terminal transcript, or chat. Removing a secret from the latest commit does not remove it from Git history.
- Use a unique production
SECRET_KEY; never deploy the example value. - Restrict PostgreSQL exposure and use managed credentials/TLS.
- Terminate HTTPS at a trusted proxy and set explicit CORS origins.
- Move browser authentication to secure, HTTP-only, same-site cookies.
- Add IP/account rate limiting to login, generation, research, chat, and exports.
- Add password reset, email verification, audit logging, and token revocation.
- Define upload/content retention policies before accepting user images or files.
- Verify licensing and terms for search, model, and source content.
- Add dependency scanning and secret scanning in CI.
The current release calls Base.metadata.create_all() during startup. This is
appropriate for an empty demo database but does not migrate changed columns or
constraints. Before changing the schema in a persistent production deployment,
introduce Alembic (or an equivalent migration system), create a baseline revision,
and run migrations as a separate release step.
The Docker volume is not a backup. For important data, schedule pg_dump to
encrypted storage, test restoration, and document retention. Exported PDF/PPTX/XLSX
files are generated on demand and are not retained by the server.
make check— deterministic backend/export logic plus frontend production build.make smoke— authenticated API/database validation workflow.- Research smoke — external search and evidence preservation.
- Cancel/resume smoke — persisted job control.
- Full smoke — live model workflow, mentor, and all exports.
Run external tests deliberately because they consume quota and depend on third-party availability.