[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10,"_11":12},"actionData","errors","root",{"_228":-5,"_231":232,"_233":234},"routes/shell",{"_40":41,"_227":-5,"_228":-5,"_229":230},"routes/repo",{"_33":-7,"_34":35,"_36":37,"_38":39,"_40":41,"_42":31,"_43":31,"_44":31,"_45":31,"_46":31,"_47":31,"_48":49,"_50":49,"_51":31,"_52":-7,"_53":-7,"_54":55,"_56":57,"_58":59,"_60":-5,"_61":62,"_63":64,"_65":66,"_67":68},"routes/repo.blob",{"_13":14,"_15":16,"_17":18,"_19":20,"_21":14,"_22":23,"_24":-5,"_25":26,"_27":28,"_28":29,"_30":31,"_32":14},"ref","b770bd2d73e574dc736bd75d303b0f0feb4d8564","path","docs/self-hosting.md","oid","993fe1f7912d3332c4dc389b74ee276b5bb30655","size",15575,"commit","mounts",[],"source","plain",{"_13":14,"_15":16},"kind","text","# Self-hosting\n\nThis guide is for operators evaluating Chopin on infrastructure they control.\nChopin is an experimental research prototype, not a supported production\nservice. Its current deployment model is one application process, one\nPostgreSQL database, one exact public origin, and a GitHub App registered for\nthat origin.\n\n## Support boundaries\n\n- GitHub.com is the only supported GitHub host.\n- Chopin must be served at the root of one origin. Subpath hosting is not\n supported.\n- HTTPS is required except for a loopback development origin.\n- The application, API, MCP endpoint, and WebSocket share one origin and one\n internal port.\n- One active Chopin process may write to a database. Horizontal application\n scaling and zero-downtime rolling deployment are not supported.\n- PostgreSQL 17 is the version used by the repository and browser tests. Other\n versions are not covered by the project test suite.\n- Database migrations are forward-only. There is no automated schema rollback.\n- Restarting the application signs every browser out and releases hosted agent\n ownership. Documents, transcripts, decisions, and implementation state remain.\n\n## Choose the access policy first\n\nEvery browser user authenticates through the GitHub App. Two optional admission\nlists decide who may enter the instance:\n\n- `GITHUB_ALLOWED_USERS` contains comma-separated GitHub logins.\n- `GITHUB_ALLOWED_ORGANIZATIONS` contains comma-separated organizations whose\n active members are admitted.\n- The lists are case-insensitive and form a union.\n- Leaving both lists empty admits every verified GitHub user.\n\nAdmission does not grant repository access. Browser routes and WebSockets also\nrequire the repository to be present in a GitHub App installation available to\nthe user. Pull access permits viewing; push or administration access permits\ncreation, editing, and Planner invocation.\n\nChopin also registers `/mcp` unconditionally. It accepts a caller-supplied\nGitHub bearer token, applies the instance admission policy, and authorizes\nrepositories directly from that token. It does not require a GitHub App\ninstallation and can create documents or advance implementation lifecycle\nstate for callers with push or administration access. `AGENT=off` disables\nhosted agent turns; it does not disable MCP.\n\nUse restricted admission for any internet-facing evaluation unless unrestricted\naccess is a deliberate choice. Protect the entire origin with TLS because MCP\nbearer tokens and browser sessions traverse it.\n\n## Prerequisites\n\n- Docker for the application image, or Bun 1.3.2 for a source deployment.\n- A reachable PostgreSQL database and credentials with schema migration access.\n- A stable DNS name with TLS termination and WebSocket proxying.\n- Outbound HTTPS access to GitHub and the hosted Copilot service.\n- A GitHub App owned by the deployment.\n- At least one user with repository push or administration access.\n- An active Copilot entitlement for each user who may own a hosted agent\n session.\n\n## Register the GitHub App\n\nCreate one GitHub App per deployment. Register the exact public origin:\n\n```text\nHomepage URL: \nCallback URL: /auth/github/callback\nSetup URL: /auth/github/setup\n```\n\nEnable expiring user authorization tokens, leave OAuth during installation and\ndevice flow disabled, disable webhooks, and make the App installable on any\naccount. The complete product uses these read-only repository permissions:\n\n```text\nContents: Read-only\nPull requests: Read-only\nChecks: Read-only\nCommit statuses: Read-only\nMetadata: Read-only (automatic)\n```\n\nOrganization admission additionally requires organization Members read access\nand owner approval on every admitted organization. See\n[Authentication](authentication.md) for the complete identity, installation,\nsession, and authorization model.\n\n## Runtime configuration\n\nStore production values in the deployment's secret manager or an owner-readable\nenvironment file outside the source tree. Do not bake `.env` or credentials into\nthe image.\n\n| Variable | Default | Meaning |\n| ------------------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |\n| `STORAGE_DRIVER` | `postgres` | Storage adapter. `postgres` is currently the only accepted value. |\n| `DATABASE_URL` | required | `postgres:` or `postgresql:` connection URL. It is not printed by Chopin. |\n| `APP_ORIGIN` | required | Exact public origin, without credentials, path, query, fragment, or trailing slash. HTTPS is required unless the host is loopback. |\n| `GITHUB_APP_SLUG` | required | Lowercase slug from the App's public URL. |\n| `GITHUB_APP_CLIENT_ID` | required | OAuth client ID, not the numeric GitHub App ID. |\n| `GITHUB_APP_CLIENT_SECRET` | required | OAuth client secret used for user-token exchange and refresh. |\n| `GITHUB_ALLOWED_USERS` | empty | Comma-separated admitted GitHub logins. |\n| `GITHUB_ALLOWED_ORGANIZATIONS` | empty | Comma-separated organizations whose active members are admitted. |\n| `SESSION_ENCRYPTION_KEY` | required | Exactly 64 hexadecimal characters used for the encrypted OAuth attempt cookie, including its validated return path. |\n| `SERVER_HOST` | `127.0.0.1` | Source-process bind address. The image sets `0.0.0.0`. |\n| `PORT` | `8787` | Source-process HTTP and WebSocket port. The supplied image and health check expect internal port 8787. |\n| `MODEL` | `claude-sonnet-4.6` | Model requested for hosted agent sessions. |\n| `AGENT` | on | Set exactly `off` to prevent hosted agent turns and Copilot CLI startup. |\n| `COPILOT_CLI_PATH` | automatic | Advanced override for the Copilot CLI executable. |\n\nGenerate the encryption key with:\n\n```bash\nopenssl rand -hex 32\n```\n\nThe image expects to listen on internal port 8787. Do not override `PORT` in the\nsupplied image without also replacing its health check and container routing.\n\n## Deploy the Docker image\n\nThe `Dockerfile` builds the browser client and one runtime image. The Bun server\nserves static assets, HTTP routes, `/mcp`, and `/ws` from the same process. Its\ndefault command applies migrations before starting the server and runs as the\nunprivileged `bun` user.\n\nBuild an image from a reviewed commit:\n\n```bash\ndocker build --tag chopin:local .\n```\n\nCreate an environment file such as `/etc/chopin/chopin.env`:\n\n```dotenv\nSTORAGE_DRIVER=postgres\nDATABASE_URL=postgresql://:@:5432/\nAPP_ORIGIN=https://chopin.example\nGITHUB_APP_SLUG=\nGITHUB_APP_CLIENT_ID=\nGITHUB_APP_CLIENT_SECRET=\nGITHUB_ALLOWED_USERS=\nGITHUB_ALLOWED_ORGANIZATIONS=\nSESSION_ENCRYPTION_KEY=<64-hex-character-key>\nAGENT=on\nMODEL=claude-sonnet-4.6\n```\n\nRestrict that file to the deployment account, then start the image behind a\nsame-host reverse proxy:\n\n```bash\ndocker run --detach \\\n --name chopin \\\n --restart unless-stopped \\\n --env-file /etc/chopin/chopin.env \\\n --publish 127.0.0.1:8787:8787 \\\n chopin:local\n```\n\nIf the reverse proxy is another container, attach both containers to a private\nnetwork instead of publishing the application port. Ensure the database address\nin `DATABASE_URL` is reachable from the application container.\n\n### Reverse proxy requirements\n\nThe proxy must:\n\n- terminate TLS for the exact `APP_ORIGIN`;\n- forward the original `Host` and `Origin` headers;\n- proxy WebSocket upgrades on `/ws`;\n- proxy `/mcp` without removing its `Authorization` header;\n- serve Chopin at `/`, not below a path prefix; and\n- redirect alternate hosts to the canonical origin before application traffic.\n\nChopin derives OAuth callbacks from `APP_ORIGIN`, never from incoming `Host` or\nforwarded headers. A proxy cannot repair a mismatched configuration after the\nprocess starts.\n\n## Checked-in Compose files\n\nThe checked-in Compose files support repository development and the project's\nCoolify deployment; they are not a complete generic production stack.\n\n`compose.yaml` publishes no host ports, uses a fixed internal development\ndatabase credential, and includes Coolify late-binding variables. The local\ncommands merge `compose.local.yaml`, which currently publishes application port\n8787 and PostgreSQL port 5432 on every host interface:\n\n```bash\nbun run db:up # start only PostgreSQL for source development\nbun run docker:up # build and start the application and PostgreSQL\n```\n\nUse those commands only on a trusted, firewalled development machine. Do not\nattach `compose.local.yaml` to an internet-facing deployment. Both\n`bun run db:down` and `bun run docker:down` tear down the whole Compose project.\n\nCoolify supplies the public proxy and can substitute `SERVICE_NAME_DB` and\n`SERVICE_FQDN_APP`. Configure `APP_ORIGIN` as\n`https://${SERVICE_FQDN_APP}` and provide all GitHub, admission, model, and\nencryption values as runtime variables. Preview-specific late-binding and\ncredential isolation are described in [PR preview testing](preview-testing.md).\n\n## Deploy from source\n\nA source deployment must build the client, apply migrations, and start the\nserver as three distinct operations:\n\n```bash\nbun install --frozen-lockfile\nbun run build\nbun run migrate\nexec bun apps/server/src/main.ts\n```\n\nAll runtime configuration, including the GitHub App values, is required by the\nmigration command. `bun run start` starts the server but does not build the\nclient or migrate the database. A missing client build allows the API process to\nstart while the browser route returns 404.\n\nRun the direct server command under a process manager that restarts it after any\nunexpected exit. Some fatal runtime paths drain successfully and exit with code\nzero, so a policy equivalent to `Restart=on-failure` is insufficient.\n\n## First-start smoke test\n\nStartup validates configuration, database connectivity, migration history, and\nthe exclusive writer lease before serving traffic. It does not fully validate\nthe GitHub App, Copilot entitlement, model, or lazy Planner runtime.\n\nAfter the first deployment:\n\n1. Confirm the process reports the intended restricted or unrestricted admission\n policy.\n2. Complete GitHub sign-in and return to the exact configured origin.\n3. Install the App on one non-sensitive test repository.\n4. Confirm the picker lists only expected installations and repositories.\n5. Create a channel with a user who has push or administration access.\n6. Open the channel in a second browser and verify presence and live edits.\n7. Send one `@chopin` request to verify the owner's Copilot entitlement and the\n hosted agent runtime.\n8. Connect a local coding agent and call `list_documents` if MCP is part of the\n deployment's intended surface.\n\nThe image health check calls `/api/session`. It confirms HTTP liveness but does\nnot prove that a browser bundle is present, a new database transaction can\ncomplete, GitHub is reachable, or the Planner can start.\n\n## Operations\n\n### Backups and restore\n\nPostgreSQL is the durable system of record. Back up the complete database with\nthe database provider's consistent backup mechanism; copying only selected\ntables or the application container is not sufficient. Regularly test restore\ninto an isolated database before relying on the backup.\n\nStop Chopin before replacing a database from a backup. Starting against the\nrestored database validates migration checksums and acquires a new writer lease.\nBrowser sessions and Planner ownership are cleared at startup.\n\n### Upgrades\n\n1. Back up the database and retain the currently deployed image.\n2. Stop the existing application process.\n3. Start the new image against the same database; its entrypoint applies pending\n migrations before serving.\n4. Repeat the first-start checks after migrations or authentication changes.\n\nMigration files are checksummed once applied. Never edit an applied migration.\nBecause migrations are forward-only, returning to an older application image\nmay require restoring the pre-upgrade database rather than merely changing the\nimage tag.\n\n### Writer lease\n\nThe database holds one renewable `chopin:writer` lease. A second application\nprocess refuses startup. If the active process loses the lease, it drains and\nstops; fencing prevents an expired process from committing collaboration state.\nAllow the previous lease to expire before treating a failed host as safely\nreplaced.\n\n## Troubleshooting\n\n**OAuth returns to an error page.** Confirm `APP_ORIGIN`, the callback URL, and\nthe browser origin match exactly. A trailing slash or reverse-proxy hostname\nchange requires a configuration restart and corresponding GitHub App update.\n\n**No repositories appear.** Authorization and installation are separate. Check\nthat the App is installed on the repository, the signed-in user can access that\ninstallation, and any new permission is approved by the organization owner.\n\n**Organization admission is temporarily unavailable.** Confirm the App has\nMembers read access, the organization approved it, and the user has active\nmembership. GitHub outages and rate limits fail closed for new checks.\n\n**A second process refuses startup.** Another holder owns the database writer\nlease. Do not run two application instances against one database.\n\n**The UI returns 404 while APIs respond.** The source deployment did not build\n`apps/web/dist`, or the runtime image was assembled incorrectly.\n\n**The first Planner turn fails.** Check the invoking user's Copilot entitlement,\nthe model, App permissions, repository write access, and Copilot CLI startup\nlogs. These dependencies are validated lazily.\n\n**MCP returns 401 or 403.** A 401 indicates an invalid or expired bearer. A 403\nindicates failed instance admission or a supplied Origin that differs from\n`APP_ORIGIN`. Repository authorization failures normally arrive as an MCP tool\nerror with reason `repository-forbidden`. See\n[Local agent MCP](local-agent-mcp.md) for client-specific guidance.\n\n## Related references\n\n- [Authentication](authentication.md)\n- [Hosted agent (Planner)](hosted-agent.md)\n- [Local agent MCP](local-agent-mcp.md)\n- [Storage](storage.md)\n- [Repository channels](channels.md)\n- [exe.dev development](exe-dev.md)\n","editable",false,"branch","documentNavigation","repo","githubnext/chopin","repoId","7d1a8ac3-35b0-4dea-85d4-06a980f3bada","ownerId","org:89615882","site","nexthub","private","admin","settings","maintainer","triage","starred","stars",0,"watchers","watching","pinned","notify","views",[183,184,185,186,187,188,189,190,191,192,193,194,195],"navigation",{"_54":55,"_139":140,"_141":142,"_143":144,"_145":146,"_147":148,"_149":150},"sources",[],"viewer","meta",{"_131":132,"_133":134,"_135":136,"_42":31,"_137":126,"_138":31,"_48":49,"_50":49},"branches",[73,74,75,76,77,78,79,80,81,82,83,84,85,86,87,88,89,90,91,92,93,94,95,96,97,98,99,100,101,102,103,104,105,106,107,108,109,110,111,112,113,114,115,116,117,118,119,120,121,122,123,124,125,126,127,128,129,130],"tags",[69,70,71,72],"cloneUrl","https://git.nexthub.sh/githubnext/chopin.git","color-controls-slice-1","color-controls-slice-2","color-controls-slice-3","color-controls-slice-4","Krzysztof-Cieslak-patch-1","Krzysztof-Cieslak-patch-2","Maggie/app-preview-toolkit","Maggie/ci-playwright-install-timeout","Maggie/collaborative-visual-decision","Maggie/design-audit","Maggie/generic-visual-decision-runtime","Maggie/impeccable-chopin-metadata","Maggie/jev-chat-product","Maggie/jev-composed-assessment","Maggie/native-document-layouts","Maggie/openui-composition-product","Maggie/openui-composition-trial","Maggie/planner-visual-authoring","Maggie/planner-visual-requests","Maggie/visual-selection-eval","artifacts/pr-419-live-preview-20261009","automation/pr-maintenance-state","automation/use-effect/callout-disabled-picker-8cf9e49ba5c09471","automation/use-effect/collaboration-options-ref-4e3a5a08a879a5ae","automation/use-effect/room-workspace-effective-access-a57d40866c71bed0","chore/bun-1.4.2","color-controls","color-controls-plan","comments","design-pr-assets","design/archived-decisions-badge","design/channel-route-remount","design/chat-decision-entry","design/conversation-analysis-markers","design/decision-evidence","design/settled-line-icon","dev/integration","diagram-step-controls","feat/liveapp-frontend-pilot","feat/local-experiments","feat/local-launcher-tracer","fix/autolink-mdx-crash","github-pills/2-pills","github-pills/3-hover-card","maggie/app-preview-toolkit","maggie/ci-playwright-install-timeout","maggie/collaborative-visual-decision","maggie/design-audit","maggie/generic-visual-decision-runtime","maggie/impeccable-chopin-metadata","maggie/jev-composed-assessment","maggie/native-document-layouts","maggie/openui-composition-product","maggie/openui-composition-trial","maggie/planner-visual-authoring","maggie/planner-visual-requests","maggie/visual-selection-eval","main","plain-text-fence-chrome","tokens/09-copy","wireframes/2-renderer","wireframes/3-planner","description","Let's compose rich plans together","owner","githubnext","section","","head","empty","pins",[165,166,167],"documents",{"_160":161,"_162":163},"code",{"_156":157,"_158":159},"automations",{"_153":154,"_155":-5},"delivery",{"_151":49,"_152":-5},"tag","04zvKQ8QOrDUF8TO1Ovz0Zy8_TT","releases","applications","workflows",3,"deployments","commits",1000,"changes",13,"counts",{"_164":163},"total",11,"issue",{"_168":158,"_170":181,"_15":158,"_172":182,"_52":174,"_175":31,"_176":174,"_177":159},{"_168":178,"_170":179,"_15":178,"_172":180,"_52":174,"_175":31,"_176":174,"_177":49},{"_168":169,"_170":171,"_15":169,"_172":173,"_52":174,"_175":31,"_176":174,"_177":163},"id","issues","name","Issues","filters",{},true,"saved","pinnable","count","tasks","Tasks",{},"Changes",{},{"_168":158,"_170":181,"_15":158,"_172":226,"_52":174,"_175":31,"_176":174},{"_168":178,"_170":179,"_15":178,"_172":225,"_52":174,"_175":31,"_176":174},{"_168":169,"_170":171,"_15":169,"_172":224,"_52":174,"_175":31,"_176":174},{"_168":221,"_170":222,"_15":221,"_172":223,"_52":31,"_175":31,"_176":174},{"_168":218,"_170":219,"_15":218,"_172":220,"_52":31,"_175":31,"_176":174},{"_168":153,"_170":216,"_15":145,"_172":217,"_52":31,"_175":31,"_176":174},{"_168":155,"_170":213,"_15":214,"_172":215,"_52":31,"_175":31,"_176":174},{"_168":151,"_170":211,"_15":151,"_172":212,"_52":31,"_175":31,"_176":174},{"_168":207,"_170":208,"_15":209,"_172":210,"_52":31,"_175":31,"_176":174},{"_168":141,"_170":205,"_15":141,"_172":206,"_52":31,"_175":31,"_176":31},{"_168":202,"_170":203,"_15":202,"_172":204,"_52":31,"_175":31,"_176":31},{"_168":199,"_170":200,"_15":199,"_172":201,"_52":31,"_175":31,"_176":31},{"_168":196,"_170":197,"_15":196,"_172":198,"_52":31,"_175":31,"_176":31},"decisions","Decisions",{},"changelog","Changelog",{},"roadmap","Roadmap",{},"Documents",{},"activity","Activity","insights",{},"Releases",{},"Deployments","automations/deployments",{},"Workflows",{},"discussions","Discussions",{},"goals","Goals",{},{},{},{},"groups","user","agents",[],"now",1794435647553,"sidebar","expanded"]