Render and Docker

One image runs the API and /mcp, and includes the folio-board remote CLI. GitHub, SQLite and Postgres share the same source permissions and board operations. Environment configuration names secrets; generated config does not contain them.

Choose persistence before deploying

Deployment	Data	Cost and limits
Render Free + Supabase Free	Postgres stores cards and authorization. Git remains authoritative for repository sources.	No paid disk. Supabase Free quotas and inactivity pauses apply; Render sleeps when idle. Check account billing and usage limits first.
Docker + SQLite	Named volume stores cards and authorization.	No hosting subscription when using a machine you already operate. You provide uptime, TLS and backups.
Docker + vanilla Postgres	Standard Postgres stores cards and authorization.	Same adapter as Supabase. Hosting and backups depend on your chosen machine or provider.

Render Free uses Postgres without a persistent disk

render.yaml selects Free, one Docker instance and /healthz. It registers Postgres beside GitHub sources and uses the same database for authorization. It creates no persistent Render disk or paid compute plan.

Set FOLIO_BOARD_DATABASE_URL securely in Render. For Supabase, use the shared pooler in session mode; no paid IPv4 add-on is required. Confirm that the Supabase organization is on Free before creating or selecting the project. Postgres documents connections and quotas; authorization storage documents sessions and tokens.

Keep the existing service URL, GitHub callback, App credentials and current FOLIO_BOARD_SESSION_KEY when updating a service. Generate a key only for a new installation. Select the reviewed branch before deploying; the Blueprint normally follows main and auto-deploy waits for its checks.

The preset uses FOLIO_BOARD_EPHEMERAL=true. Startup refuses SQLite sources and requires remote authorization storage in account mode. Local clones and runtime configuration are disposable; cards and credentials stay in Postgres.

After deployment, the configured Personal board appears in the source selector alongside authorized repositories. Set Postgres readers and writers using stable numeric GitHub subjects. Access defaults deny other accounts; Settings → Sources selects what the canvas loads.

Render Free sleeps after 15 idle minutes and may take about a minute to wake. Its 750 free instance hours are shared per workspace. Transfer or build usage can be billed when a payment method is present: verify billing before claiming a deployment costs $0. Supabase Free can restrict excess usage and pause after a week of inactivity. Sources: Render Free , Supabase Free , Supabase costs .

Docker Compose retains SQLite in a named volume

Copy deploy/hosted/env.example to .env, fill the App values and generate a signing key once. Configure your public HTTPS API address and frontend origin. Point an HTTPS reverse proxy at the container’s loopback port.


cp deploy/hosted/env.example .env
openssl rand -hex 32
gh api user --jq .id
docker compose up --build -d

Put the generated key in .env as FOLIO_BOARD_SESSION_KEY and keep it across replacements. Use the numeric id in FOLIO_BOARD_SQLITE_WRITERS, for example ["github:123456"]. Secrets, database files and private keys are excluded from the image build context.

Compose persists board-data at /home/board/data. The entrypoint prepares the directory, then runs the server and CLI as board. docker compose down retains the volume; removing it removes its data.

To use Postgres instead, disable SQLite, enable Postgres and select its connection variable for authorization as shown in the example’s comments. The connection can point to vanilla Postgres or Supabase. Remote connections require verified TLS; loopback or Unix sockets can explicitly disable TLS for local development.

Location	Contents	Persistence
`boards/<id>.sqlite3` and WAL files	SQLite cards and revisions	Named volume required
`.auth/security.sqlite3` and WAL files	SQLite authorization	Named volume required
Private Postgres `folio_board` and `folio_auth` schemas	Remote cards and authorization	Database host and backups
`clones/` and `project/agents.yaml`	Rebuildable clones and generated config	Disposable when using remote persistence

Runtime options keep providers separate

Variable	Default	Meaning
`FOLIO_BOARD_AUTH`	`github`	Web account login; `token` selects standalone bearer access
`FOLIO_BOARD_SQLITE`	`true`	Register the default SQLite board
`FOLIO_BOARD_POSTGRES`	`false`	Register the default Postgres board
`FOLIO_BOARD_POSTGRES_CONNECTION_ENV`	`FOLIO_BOARD_DATABASE_URL`	Name of the connection secret variable
`FOLIO_BOARD_POSTGRES_ID`, `FOLIO_BOARD_POSTGRES_TITLE`	`postgres`, `Postgres`	Stable source id and title
`FOLIO_BOARD_POSTGRES_BOARD`	Source id	Opaque database board id
`FOLIO_BOARD_SQLITE_ID`, `FOLIO_BOARD_SQLITE_TITLE`	`database`, `SQLite`	Stable source id and title
`FOLIO_BOARD_SQLITE_READERS/WRITERS`, `FOLIO_BOARD_POSTGRES_READERS/WRITERS`	`[]`	JSON arrays of stable subjects
`FOLIO_BOARD_AUTH_CONNECTION_ENV`	Absent	Select Postgres authorization; otherwise uses SQLite
`FOLIO_BOARD_AUTH_DB`	`<data>/.auth/security.sqlite3`	SQLite authorization file
`FOLIO_BOARD_EPHEMERAL`	`false`	Refuse SQLite and require remote account authorization
`FOLIO_BOARD_SOURCES`	`[]`	More sources through the common `board.sources` contract
`FOLIO_BOARD_DATA_DIR`	`/home/board/data`	Runtime directory; mount a volume when using SQLite
`FOLIO_BOARD_READ_ONLY`	`false`	Refuse card writes; databases must already exist
`FOLIO_BOARD_ORIGIN`, `FOLIO_BOARD_PUBLIC_URL`	Required	Frontend origin and public HTTPS API address

GitHub account mode can enable both databases or only GitHub repositories. Optional FOLIO_BOARD_SQLITE_SEED or FOLIO_BOARD_POSTGRES_SEED imports a mounted board once. Additional sources use the same reader/writer rules.

Standalone FOLIO_BOARD_AUTH=token requires exactly one enabled database and FOLIO_BOARD_TOKEN with at least 32 characters. It needs no GitHub credentials, and provides no GitHub login or personal token issuance. The frontend selects kanban.api.auth: token explicitly.

CLI and MCP use the same endpoint

Issue a token in Settings → API tokens, then set FOLIO_BOARD_API and FOLIO_BOARD_TOKEN in the tool environment. The token is never a command argument.


docker compose run --rm -e FOLIO_BOARD_API -e FOLIO_BOARD_TOKEN board folio-board board

A supplied command runs as board without requiring backend configuration. For direct image use:


docker run --rm -e FOLIO_BOARD_API -e FOLIO_BOARD_TOKEN folio-board:local folio-board board

Readiness at /healthz is public; card and MCP requests require authorization. Remote CLI, MCP, storage and backups.