Bytebase service itself does not provide native HTTPS support. We recommend using a reverse proxy (Nginx, Caddy) on the same VM for Docker deployments, or ingress/gateway for Kubernetes deployments.
Docker Deployment with Reverse Proxy
When deploying Bytebase with Docker on a VM, use a reverse proxy for external access and HTTPS termination.Nginx Configuration
For Docker deployments using Nginx as a reverse proxy:Common Issue: 502 Bad Gateway
If you’re getting 502 errors, ensureproxy_pass points to the actual Bytebase service, not the nginx domain itself (which creates a loop):
Caddy Configuration
For Docker deployments using Caddy (automatic HTTPS with Let’s Encrypt):- Install Caddy on your VM
- Save the configuration to
/etc/caddy/Caddyfile - Run:
caddy reload
Kubernetes Deployment
For Kubernetes deployments, use ingress controllers or gateways to configure external access with HTTPS support.Nginx Ingress Controller
Deploy Bytebase with Nginx Ingress Controller:Kubernetes Gateway API
For modern Kubernetes deployments using Gateway API:Service Configuration
Ensure your Bytebase service is configured correctly:Restricting Network Exposure
Bytebase serves everything from one HTTP port and does not gate any of it by hostname, listener, source network, or client certificate.X-Real-IP and X-Forwarded-For are recorded in the audit log but never affect authorization. Any network-level restriction has to be enforced at your reverse proxy or ingress.
What must reach what
Surface reduction is not a security boundary
What does hold:- Restricting the whole deployment,
/v1/*and/bytebase.v1.*alike, to trusted networks or clients. - Serving
/v1/*on an internal hostname for automation, separate from the hostname humans use. - Keeping
/metrics,/grpc.reflection.*, and/debug/pprof/*off any public hostname./hook/scim/*must stay reachable from your identity provider.
Authentication entry points
Password, SSO, and service account sign-in share one flow and are told apart by the request body, so no proxy rule can allow SSO while denying password sign-in. Use Enforce SSO sign-in for that. Workload identity is the only machine sign-in with an endpoint of its own, which makes it the one to confine to an internal entry point.
Serving several hostnames
- SSO completes only on the hostname in External URL: Bytebase redeems the authorization code with a callback built from External URL, and the identity provider rejects the exchange when the browser started from another origin.
- Session cookies are scoped to the host that issued them, so users sign in separately on each hostname.
- External URL is a single value. Set it to the hostname your users visit.
Additional Configuration
Configure External URL
For production usage, configure the External URL to match your domain. See Configure External URL for details.WebSocket Support
SQL Editor autocomplete requires WebSocket support. All configurations above include the necessary WebSocket settings. Key endpoints that require WebSocket:/v1:adminExecute- For SQL execution/lsp- For Language Server Protocol (autocomplete)
Troubleshooting
- WebSocket issues: Verify proxy/ingress WebSocket configuration
- 502 errors: Check Bytebase service status
- Timeout errors: Increase proxy timeout settings (see examples above)

