🐳 feat: Bundle Admin Panel in Docker Compose Stacks

[danny-avila]

Summary

I bundled the LibreChat Admin Panel into both Docker Compose stacks so a default deployment ships with the admin panel running alongside LibreChat, with no extra setup. The panel is an API client (it reaches LibreChat over the REST API, not the database directly), so it only needs to talk to the api service.

• Added an admin-panel service to docker-compose.yml, published on a host port (http://localhost:3000 by default, overridable via ADMIN_PANEL_PORT). It points API_SERVER_URL at http://api:${PORT} for server-side calls and VITE_API_BASE_URL at DOMAIN_CLIENT for browser-facing OAuth redirects.
• Added an admin-panel service to deploy-compose.yml with no published port, fronted by the existing nginx reverse proxy and served at the http://admin.localhost subdomain.
• Set ADMIN_PANEL_URL=http://admin.localhost on the deploy-compose api service so LibreChat builds admin OAuth/SSO callbacks against the subdomain, and added admin-panel to the nginx client service's depends_on.
• Added an admin.localhost server block to client/nginx.conf that proxies to admin-panel:3000. It resolves the upstream through Docker's embedded DNS (127.0.0.11) with a variable, so nginx still starts when the admin-panel service is absent (this config is also shared by utils/docker/test-compose.yml). Added a $connection_upgrade map for WebSocket/SSE passthrough and a commented SSL variant mirroring the existing one.
• Added ADMIN_PANEL_SESSION_SECRET to .env.example with a development default (the panel requires a 32+ char secret and the image has no built-in default, so "always on" must work out of the box), matching the existing convention for CREDS_KEY/JWT_SECRET/MEILI_MASTER_KEY. Documented ADMIN_PANEL_PORT.

Access

• Default stack (docker-compose.yml): http://localhost:3000
• Deploy stack (deploy-compose.yml): http://admin.localhost (browsers resolve *.localhost to 127.0.0.1 automatically; non-browser tools may need a hosts entry)

Notes

• The panel runs by default in both stacks. To opt out, remove the admin-panel service or gate it behind a compose profiles: entry.
• SESSION_COOKIE_SECURE defaults to false for plain-HTTP local use; set it to true (via ADMIN_PANEL_SESSION_COOKIE_SECURE) when serving the panel over HTTPS.
• Production hardening: rotate ADMIN_PANEL_SESSION_SECRET, point DOMAIN_CLIENT and ADMIN_PANEL_URL at real domains, and terminate TLS.

Change Type

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Testing

I validated the configuration statically without booting the full stack:

• docker compose -f docker-compose.yml config and docker compose -f deploy-compose.yml config both render cleanly; the admin-panel service resolves its env, the deploy api service receives ADMIN_PANEL_URL=http://admin.localhost, and the nginx client service depends on admin-panel.
• nginx -t passes against the updated client/nginx.conf.
• Confirmed the ghcr.io/clickhouse/librechat-admin-panel:latest image manifest exists and is multi-arch (amd64 + arm64).

Recommended follow-up smoke test: cp .env.example .env, then docker compose up and confirm the panel loads at http://localhost:3000; and docker compose -f deploy-compose.yml up, then confirm http://admin.localhost loads and email/password login against LibreChat succeeds.

Test Configuration:

• Docker 29.x, nginx 1.27.0-alpine

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• I have commented in any complex areas of my code
• My changes do not introduce new warnings