# Deploying

Self-hosting is free under AGPL-3.0-only: no license charge, no per-seat fee, no payment markup. You operate the infrastructure, storage, AI provider and bank relationship. This page describes the shape; the [source repo](https://github.com/VisiOffice/Payvy) (Dockerfile, docker-compose) is the working reference.

## The pieces

- **App:** one server process (the Dockerfile's app target). It applies database migrations at startup and serves the API, MCP endpoint, webhooks, and — with `PAYVY_WEB_DIR` set — the built web app.
- **Database:** Postgres. Isolation between organizations relies on row-level security, so the app role must own the database but **not** be a superuser, or RLS won't hold.
- **Documents:** an S3-compatible bucket you control (see [Configuration](https://docs.payvy.com/self-hosting/configuration/)).
- **Ingress:** put the app behind a reverse proxy with TLS. `/webhooks/email` must be reachable from the internet if you use [email intake](https://docs.payvy.com/guide/email-intake/) (a Cloudflare Tunnel also works).

## Secrets you must keep

Generate with `openssl rand -hex 32` and store in your password manager, not in the repo:

- `PAYVY_API_KEY` and `PAYVY_INBOUND_SECRET` (32+ characters each)
- `PAYVY_SECRETS_KEY` — seals bank tokens. **Losing it means reconnecting every bank.** Losing the database without it pays no one, which is the point.
- Your S3, model-provider, and mail-sender credentials

## Before you pay real bills

1. Create the first person (`payvy person add --email … --name …`) and sign in.
2. Create your inbound address (`email.new_address`) and send a test bill.
3. Connect Mercury in `request` mode first (second sign-off inside Mercury) and pay a small bill end to end; switch to `direct` only deliberately, with the server IP on the token's allowlist.
4. Score your extraction model (`payvy extract-eval fixtures/invoices`) before letting drafts flow unattended.

## Backups & upgrades

Back up Postgres and the document bucket together — bills reference documents by content hash, and either alone is half a record. Retention and access on the bucket are yours, as they were for your filing cabinet. Upgrade by deploying a new build: migrations run at startup, and workflow versions pinned by in-flight bills are unaffected by workflow edits.

:::caution
Payvy is in development. Hosted Payvy (planned $39 bring-your-own-agent / $99 managed-agent per company) will run this same software operated by us; self-hosting remains free. See [payvy.com/pricing](https://payvy.com/pricing/).
:::