Skip to main content
This guide covers how to configure external access for your Bytebase deployment across different deployment methods.
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, ensure proxy_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):
To use this Caddy configuration:
  1. Install Caddy on your VM
  2. Save the configuration to /etc/caddy/Caddyfile
  3. 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

/metrics answers loopback callers only unless Bytebase runs with --metrics-remote-access, and a reverse proxy on the same host counts as loopback. If the proxy forwards /metrics, restrict it there.

Surface reduction is not a security boundary

Blocking /v1/* on the hostname your users visit changes nothing. The web console does not use /v1/*, so it keeps working and the block looks effective, while every operation stays reachable over /bytebase.v1.*: both surfaces are generated from the same API definitions.
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)