> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bytebase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External Access Configuration

This guide covers how to configure external access for your Bytebase deployment across different deployment methods.

<Note>
  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.
</Note>

## 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:

```nginx theme={null}

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) {
            # Point to the actual Bytebase service, NOT the nginx domain
            proxy_pass http://127.0.0.1:8080;  # If Bytebase runs on the same host
            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 / {
            # Point to the actual Bytebase service, NOT the nginx domain
            proxy_pass http://127.0.0.1:8080;  # If Bytebase runs on the same host
        }

        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}
```

#### 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):

```nginx theme={null}
# ❌ WRONG - Creates proxy loop
proxy_pass http://bytebase.example.com;

# ✅ CORRECT - Points to Bytebase service
proxy_pass http://127.0.0.1:8080;      # Same host
proxy_pass http://bytebase:8080;        # Docker Compose service name
proxy_pass http://10.0.0.5:8080;        # Different host IP
```

### Caddy Configuration

For Docker deployments using Caddy (automatic HTTPS with Let's Encrypt):

```caddy theme={null}
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](https://kubernetes.github.io/ingress-nginx/deploy/):

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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](/get-started/self-host/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)