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: 

http {
    map $http_upgrade $connection_upgrade {
      default upgrade;
      '' close;
    }

    server {
        listen       80;
        listen  [::]:80;
        # Listen HTTPS
        listen       443 ssl;
        listen  [::]:443 ssl;
        server_name  bytebase.example.com;

        # SSL cert and key
        ssl_certificate /path/to/certificate/file;
        ssl_certificate_key /path/to/private/key/file;

       location ~ ^/(v1:adminExecute|lsp) {
            proxy_pass http://bytebase.example.com;
            proxy_http_version 1.1;
            # Enables WebSocket which is required for SQL Editor autocomplete
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }

        location / {
            proxy_pass http://bytebase.example.com;
        }

        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

​
Caddy Configuration

For Docker deployments using Caddy (automatic HTTPS with Let’s Encrypt): 
bytebase.example.com {
    # Automatic HTTPS with Let's Encrypt
    
    # Reverse proxy to Bytebase
    reverse_proxy localhost:8080 {
        # Timeouts for long-running operations
        transport http {
            read_timeout 3600s
            write_timeout 3600s
        }
    }
}
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: 
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: bytebase-ingress
  namespace: default
  annotations:
    # Enable HTTPS redirect
    nginx.ingress.kubernetes.io/ssl-redirect: 'true'
    
    # WebSocket support for SQL Editor
    nginx.ingress.kubernetes.io/proxy-read-timeout: '3600'
    nginx.ingress.kubernetes.io/proxy-send-timeout: '3600'
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - bytebase.example.com
      secretName: bytebase-tls-secret
  rules:
    - host: bytebase.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: bytebase-service
                port:
                  number: 8080

​
Kubernetes Gateway API

For modern Kubernetes deployments using Gateway API: 
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bytebase-route
  namespace: default
spec:
  parentRefs:
    - name: gateway
      namespace: default
  hostnames:
    - bytebase.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        - name: bytebase-service
          port: 8080
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: gateway
  namespace: default
spec:
  gatewayClassName: nginx
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      tls:
        mode: Terminate
        certificateRefs:
          - name: bytebase-tls-secret
    - name: http
      protocol: HTTP
      port: 80
      # Redirect HTTP to HTTPS
      allowedRoutes:
        namespaces:
          from: Same

​
Service Configuration

Ensure your Bytebase service is configured correctly: 
apiVersion: v1
kind: Service
metadata:
  name: bytebase-service
  namespace: default
spec:
  selector:
    app: bytebase
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  type: ClusterIP

​
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)