Run the airmux image and Postgres with persistent named volumes.
Docker Compose runs airmux and Postgres. The CLI is available inside the app container.
Start
Follow the quickstart to download the release’s Compose file and start the stack:
docker compose up -d --wait
Compose creates airmux-config automatically. The stack uses the bundled configuration until you add a custom YAML file.If you need to customize the deployment see Customize the runtime YAML.
Set these in .env and restart Compose. For a public deployment, terminate TLS at a
reverse proxy and set AIRMUX_PUBLIC_URL to the exact HTTPS origin.Once your deployment is available, open its URL in a browser and follow the setup steps.Or set up the instance through the CLI using the same URL:
Set a URL-safe POSTGRES_PASSWORD before the first start of a public installation. Changing the Compose variable later
does not rotate the password already stored by Postgres.
Customize the runtime YAML
Use this when you need to change the control-plane or data-plane settings in the
configuration reference. If Docker created airmux-config as root on Linux, first take ownership with
sudo chown "$(id -u):$(id -g)" airmux-config. Copy the default YAML from your running image:
Edit airmux-config/airmux.yml. Keep its /state paths unless you also provide suitable persistent storage, and keep the control plane and data plane on the same secret store.The Compose file mounts ./airmux-config read-only and any change to airmux.yml will be picked up when you restart the stack. If the file is absent or empty, it will use the default YAML bundled in the image.Runtime ${env:...} references use each container’s environment, not values read directly from .env.Paths in the custom YAML resolve relative to /config, so use absolute /state/... paths for persistent data as the bundled file does. Compare your custom file with the new image’s default YAML when upgrading.Restart the stack after editing the YAML:
docker compose downdocker compose up -d --wait
If startup fails, inspect docker compose logs migrate taxonomy app. To return to the image default, remove airmux-config/airmux.yml and run the same two commands.
Startup and database changes
docker compose up runs the migration job first and the catalog job second. The app container starts only after both
jobs succeed. On later runs, migration checks the current schema revision and the catalog job reapplies the definitions
shipped with the selected image. To diagnose a failure:
docker compose down preserves both volumes. docker compose down -v deletes the complete installation.
Back up both volumes before an update, and do not use down -v unless permanent deletion is intended.
Upgrade and roll back
Read the target release notes and compare any custom runtime YAML with the target image’s
default. Record the current image digest, stop new traffic, and back up Postgres and /state together. The migration
job may change the database schema and an older image cannot safely use a database migrated by a newer release.Download the Compose file for the target release. Remove any older AIRMUX_IMAGE override from .env, then replace
the stack:
docker compose up -d --wait --remove-orphans
The application service is named app. --remove-orphans removes the previous cli service when upgrading from an older Compose file,
freeing its port for app. Keep the same Compose project name and directory to reuse the existing database and application volumes.Check /healthz on the public origin, run docker compose exec app airmux doctor, and send a buffered
and streaming request. Confirm that the requests appear in usage. If verification fails after migration, stop the new
stack, restore Postgres and /state from the same backup, and redeploy the recorded previous release. Do not roll
back only the image against the newer database.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"airmux","description":"A self-hosted LLM gateway with provider routing, scoped credentials, policies, and usage accounting.","colors":{"primary":"#2563EB","light":"#3B82F6","dark":"#1D4ED8"},"favicon":"https://mintcdn.com/airbyte-05418ec9/NNRgJD-jwhYulVok/apps/console/public/favicon.svg?fit=max\u0026auto=format\u0026n=NNRgJD-jwhYulVok\u0026q=85\u0026s=30091636fde5c5650e2c909485df676d","styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"airbyte-05418ec9","hasAudioNarration":false,"actualSubdomain":"airbyte-05418ec9","customDomains":["docs.airmux.ai"],"gitSource":{"type":"github","owner":"michel-tricot","repo":"airmux","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6abecf5beecbc5880dabeaa0","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Reference","count":106},{"language":"default","tag":"Control plane endpoints","count":97},{"language":"default","tag":"Workspace","count":31},{"language":"default","tag":"Documentation","count":27},{"language":"default","tag":"Organization","count":27},{"language":"default","tag":"Instance","count":20},{"language":"default","tag":"Account","count":14},{"language":"default","tag":"Authentication","count":10},{"language":"default","tag":"Provider Credentials","count":10},{"language":"default","tag":"Deploy and operate","count":9}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"docs/deployment/docker","slug":"/docs/deployment/docker","pageMetadata":{"title":"Docker Compose","description":"Run the airmux image and Postgres with persistent named volumes.","href":"/docs/deployment/docker"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Run the airmux image and Postgres with persistent named volumes.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Docker Compose runs airmux and Postgres. The CLI is available inside the `,_jsx(_components.code,{children:`app`}),` container.`]}),`\n`,_jsx(Heading,{level:`2`,id:`start`,children:`Start`}),`\n`,_jsxs(_components.p,{children:[`Follow the `,_jsx(_components.a,{href:`/docs/quickstart`,children:`quickstart`}),` to download the release’s Compose file and start the stack:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` up`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --wait`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Compose creates `,_jsx(_components.code,{children:`airmux-config`}),` automatically. The stack uses the bundled configuration until you add a custom YAML file.`]}),`\n`,_jsxs(_components.p,{children:[`If you need to customize the deployment see `,_jsx(_components.a,{href:`#customize-the-runtime-yaml`,children:`Customize the runtime YAML`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`configure-the-public-origin`,children:`Configure the public origin`}),`\n`,_jsx(_components.p,{children:`For another local port:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`AIRMUX_PORT`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`9000`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#9CDCFE`},children:`AIRMUX_PUBLIC_URL`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`http://localhost:9000`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Set these in `,_jsx(_components.code,{children:`.env`}),` and restart Compose. For a public deployment, terminate TLS at a\nreverse proxy and set `,_jsx(_components.code,{children:`AIRMUX_PUBLIC_URL`}),` to the exact HTTPS origin.`]}),`\n`,_jsx(_components.p,{children:`Once your deployment is available, open its URL in a browser and follow the setup steps.`}),`\n`,_jsx(_components.p,{children:`Or set up the instance through the CLI using the same URL:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` exec`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` app`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` airmux`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` quickstart`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --url`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` https://airmux.example.com`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Set a URL-safe `,_jsx(_components.code,{children:`POSTGRES_PASSWORD`}),` before the first start of a public installation. Changing the Compose variable later\ndoes not rotate the password already stored by Postgres.`]}),`\n`,_jsx(Heading,{level:`2`,id:`customize-the-runtime-yaml`,children:`Customize the runtime YAML`}),`\n`,_jsxs(_components.p,{children:[`Use this when you need to change the control-plane or data-plane settings in the\n`,_jsx(_components.a,{href:`/docs/reference/configuration`,children:`configuration reference`}),`. If Docker created `,_jsx(_components.code,{children:`airmux-config`}),` as root on Linux, first take ownership with\n`,_jsx(_components.code,{children:`sudo chown \"$(id -u):$(id -g)\" airmux-config`}),`. Copy the default YAML from your running image:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`mkdir`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -p`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` airmux-config`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` exec`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -T`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` app`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` cat`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` /app/deploy/docker/airmux.yml`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:` >`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` airmux-config/airmux.yml`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Edit `,_jsx(_components.code,{children:`airmux-config/airmux.yml`}),`. Keep its `,_jsx(_components.code,{children:`/state`}),` paths unless you also provide suitable persistent storage, and keep the control plane and data plane on the same secret store.`]}),`\n`,_jsxs(_components.p,{children:[`The Compose file mounts `,_jsx(_components.code,{children:`./airmux-config`}),` read-only and any change to `,_jsx(_components.code,{children:`airmux.yml`}),` will be picked up when you restart the stack. If the file is absent or empty, it will use the default YAML bundled in the image.`]}),`\n`,_jsxs(_components.p,{children:[`Runtime `,_jsx(_components.code,{children:\"${env:...}\"}),` references use each container’s environment, not values read directly from `,_jsx(_components.code,{children:`.env`}),`.`]}),`\n`,_jsxs(_components.p,{children:[`Paths in the custom YAML resolve relative to `,_jsx(_components.code,{children:`/config`}),`, so use absolute `,_jsx(_components.code,{children:`/state/...`}),` paths for persistent data as the bundled file does. Compare your custom file with the new image’s default YAML when upgrading.`]}),`\n`,_jsx(_components.p,{children:`Restart the stack after editing the YAML:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` down`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` up`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --wait`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`If startup fails, inspect `,_jsx(_components.code,{children:`docker compose logs migrate taxonomy app`}),`. To return to the image default, remove `,_jsx(_components.code,{children:`airmux-config/airmux.yml`}),` and run the same two commands.`]}),`\n`,_jsx(Heading,{level:`2`,id:`startup-and-database-changes`,children:`Startup and database changes`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`docker compose up`}),` runs the migration job first and the catalog job second. The `,_jsx(_components.code,{children:`app`}),` container starts only after both\njobs succeed. On later runs, migration checks the current schema revision and the catalog job reapplies the definitions\nshipped with the selected image. To diagnose a failure:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` logs`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` migrate`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` taxonomy`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`state`,children:`State`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Volume`}),_jsx(_components.th,{children:`Contents`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`pgdata`})}),_jsx(_components.td,{children:`Postgres data`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`state`})}),_jsx(_components.td,{children:`Runtime management key, provider secrets, gateway identity, bundle cache, and usage outbox`})]})]})]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`docker compose down`}),` preserves both volumes. `,_jsx(_components.code,{children:`docker compose down -v`}),` deletes the complete installation.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Back up both volumes before an update, and do not use `,_jsx(_components.code,{children:`down -v`}),` unless permanent deletion is intended.`]})}),`\n`,_jsx(Heading,{level:`2`,id:`upgrade-and-roll-back`,children:`Upgrade and roll back`}),`\n`,_jsxs(_components.p,{children:[`Read the target release notes and compare any `,_jsx(_components.a,{href:`#customize-the-runtime-yaml`,children:`custom runtime YAML`}),` with the target image’s\ndefault. Record the current image digest, stop new traffic, and back up Postgres and `,_jsx(_components.code,{children:`/state`}),` together. The migration\njob may change the database schema and an older image cannot safely use a database migrated by a newer release.`]}),`\n`,_jsxs(_components.p,{children:[`Download the Compose file for the target release. Remove any older `,_jsx(_components.code,{children:`AIRMUX_IMAGE`}),` override from `,_jsx(_components.code,{children:`.env`}),`, then replace\nthe stack:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`docker`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` compose`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` up`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` -d`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --wait`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --remove-orphans`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`The application service is named `,_jsx(_components.code,{children:`app`}),`. `,_jsx(_components.code,{children:`--remove-orphans`}),` removes the previous `,_jsx(_components.code,{children:`cli`}),` service when upgrading from an older Compose file,\nfreeing its port for `,_jsx(_components.code,{children:`app`}),`. Keep the same Compose project name and directory to reuse the existing database and application volumes.`]}),`\n`,_jsxs(_components.p,{children:[`Check `,_jsx(_components.code,{children:`/healthz`}),` on the public origin, run `,_jsx(_components.code,{children:`docker compose exec app airmux doctor`}),`, and send a buffered\nand streaming request. Confirm that the requests appear in usage. If verification fails after migration, stop the new\nstack, restore Postgres and `,_jsx(_components.code,{children:`/state`}),` from the same backup, and redeploy the recorded previous release. Do not roll\nback only the image against the newer database.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Docker Compose","description":"Run the airmux image and Postgres with persistent named volumes.","href":"/docs/deployment/docker"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Start","slug":"start","depth":2,"children":[]},{"title":"Configure the public origin","slug":"configure-the-public-origin","depth":2,"children":[]},{"title":"Customize the runtime YAML","slug":"customize-the-runtime-yaml","depth":2,"children":[]},{"title":"Startup and database changes","slug":"startup-and-database-changes","depth":2,"children":[]},{"title":"State","slug":"state","depth":2,"children":[]},{"title":"Upgrade and roll back","slug":"upgrade-and-roll-back","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"airbyte-05418ec9","siteName":"airmux","title":"Docker Compose - airmux","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-27T05:45:57.902Z","originalFileLocation":"docs/deployment/docker.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Run the airmux image and Postgres with persistent named volumes.\">\u003cmeta data-mint-head name=\"application-name\" content=\"airmux\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Docker Compose - airmux\">\u003cmeta data-mint-head property=\"og:description\" content=\"Run the airmux image and Postgres with persistent named volumes.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"airmux\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.airmux.ai/docs/deployment/docker\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://airbyte-05418ec9.mintlify.site/_mintlify/api/og/v2?division=Deploy+and+operate\u0026amp;title=Docker+Compose\u0026amp;description=Run+the+airmux+image+and+Postgres+with+persistent+named+volumes.\u0026amp;theme=20cab0b8d8d3e93733d26c49\u0026amp;signature=e55862017138dfcc6cee0f4e505dbbd438d2d9add431e7d5e4f9e6fabefafc1b\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Docker Compose - airmux\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Run the airmux image and Postgres with persistent named volumes.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://airbyte-05418ec9.mintlify.site/_mintlify/api/og/v2?division=Deploy+and+operate\u0026amp;title=Docker+Compose\u0026amp;description=Run+the+airmux+image+and+Postgres+with+persistent+named+volumes.\u0026amp;theme=20cab0b8d8d3e93733d26c49\u0026amp;signature=e55862017138dfcc6cee0f4e505dbbd438d2d9add431e7d5e4f9e6fabefafc1b\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/airbyte-05418ec9/Xsl0Xb8mTXKxv0D_/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"airmux\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2563EB\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.airmux.ai/docs/deployment/docker\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/deployment/docker.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.airmux.ai/#organization\",\"name\":\"airmux\",\"url\":\"https://docs.airmux.ai\"},{\"@type\":\"WebSite\",\"@id\":\"https://docs.airmux.ai#website\",\"name\":\"airmux\",\"url\":\"https://docs.airmux.ai\",\"publisher\":{\"@id\":\"https://docs.airmux.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.airmux.ai/docs/deployment/docker#webpage\",\"url\":\"https://docs.airmux.ai/docs/deployment/docker\",\"name\":\"Docker Compose\",\"description\":\"Run the airmux image and Postgres with persistent named volumes.\",\"dateModified\":\"2026-09-27T05:45:57.902Z\",\"isPartOf\":{\"@id\":\"https://docs.airmux.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.airmux.ai/docs/deployment/docker#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.airmux.ai/docs/deployment/docker#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Deploy and operate\",\"item\":\"https://docs.airmux.ai/docs/deployment\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Docker Compose\",\"item\":\"https://docs.airmux.ai/docs/deployment/docker\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.airmux.ai/docs/deployment/docker#article\",\"headline\":\"Docker Compose\",\"name\":\"Docker Compose\",\"description\":\"Run the airmux image and Postgres with persistent named volumes.\",\"url\":\"https://docs.airmux.ai/docs/deployment/docker\",\"mainEntityOfPage\":{\"@id\":\"https://docs.airmux.ai/docs/deployment/docker#webpage\"},\"dateModified\":\"2026-09-27T05:45:57.902Z\",\"publisher\":{\"@id\":\"https://docs.airmux.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.airmux.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"airmux\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"airmux\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/docs/deployment/docker.md","siteName":"airmux","nav":{"global":null,"tabs":[{"tab":"Documentation","icon":"book-open","groups":[{"group":"Get started","pages":[{"title":"airmux","href":"/docs"},{"title":"Quickstart","href":"/docs/quickstart"}]},{"group":"Use the platform","pages":[{"title":"Use the CLI","href":"/docs/guides/cli"},{"title":"Use the webapp","href":"/docs/guides/webapp"},{"title":"Manage users and access","href":"/docs/guides/user-management"},{"title":"Use an SDK","href":"/docs/guides/sdks"},{"title":"Workspace policies","href":"/docs/guides/policies"},{"title":"Create and audit a budget","href":"/docs/guides/budgets"},{"title":"Model routing and failover","href":"/docs/features/model-routing"},{"title":"Provider credentials","href":"/docs/features/provider-credentials"},{"title":"Inference Usage","href":"/docs/features/usage"}]},{"group":"Deploy and operate","pages":[{"title":"Deployment overview","description":"Choose a Docker, Fly.io, Python, or split deployment and identify the required database, state, network, and public URL.","href":"/docs/deployment/index"},{"title":"Docker Compose","href":"/docs/deployment/docker"},{"title":"Fly.io","description":"Run the full airmux platform on one Fly Machine with one managed Postgres database.","href":"/docs/deployment/fly"},{"title":"Deploy without Docker","href":"/docs/deployment/without-docker"},{"title":"Gateway only","href":"/docs/deployment/gateway"},{"title":"Separate services and scale gateways","href":"/docs/deployment/scaling"},{"title":"Security checklist","href":"/docs/deployment/security"},{"title":"OpenTelemetry","href":"/docs/deployment/opentelemetry"},{"title":"Production operations","href":"/docs/deployment/operations"}]},{"group":"Concepts","pages":[{"title":"Architecture","href":"/docs/concepts/architecture"},{"title":"Canonical model","href":"/docs/concepts/canonical-model"},{"title":"Authentication and scopes","href":"/docs/concepts/authentication"},{"title":"Bundles and consistency","href":"/docs/concepts/bundles"},{"title":"Request lifecycle","href":"/docs/concepts/request-lifecycle"}]},{"group":"Contributing","pages":[{"title":"Development","href":"/docs/development"},{"title":"Release airmux","href":"/docs/releasing"}]}]},{"tab":"Reference","icon":"braces","pages":[{"title":"Reference","href":"/docs/reference/inference"}]}]},"basePath":"","title":"Docker Compose - airmux","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}