Proxy configuration

Overview

CloudBeaver includes a built-in reverse proxy for secure access and load balancing.

This article explains how to set up a proxy in the CloudBeaver Compose setup.

• CloudBeaver AWS uses the default pre-configured proxy setup as the Enterprise Edition.
• Community Edition users need to configure the proxy manually.

For proxy configuration in other deployment types, see README in the cloudbeaver-deploy repository.

Configure proxy server

Note

This feature is available in Enterprise, AWS, and Team editions only.

Starting in version 25.1, CloudBeaver supports two proxy types: Nginx and HAProxy. Set the proxy type in your .env file:

PROXY_TYPE=nginx  # Options: nginx, haproxy

If you previously used Nginx and want to switch to HAProxy, you can do it without losing configuration or SSL certificates - shared Docker volumes handle it.

Info

For details on environment configuration, see CloudBeaver Enterprise deployment from Docker Compose

Proxy ports

When using Docker Compose with network_mode: host, set ports in your .env file:

LISTEN_PORT_HTTP=80
LISTEN_PORT_HTTPS=443

These control which ports the proxy listens to inside the container.

Extra step for Nginx

If you use Nginx and set a custom COMPOSE_PROJECT_NAME in your .env, pass it explicitly in the container’s environment block:

environment:
  - COMPOSE_PROJECT_NAME=${COMPOSE_PROJECT_NAME}

Note

This isn’t needed for HAProxy - it resolves service names via Docker DNS.

Force HTTPS mode

Force HTTPS enforces secure connections across the entire application. When this option is enabled, the server automatically redirects all HTTP requests to HTTPS and sets cookies with the Secure flag, so they’re never sent over unencrypted channels.

Why enable force HTTPS

• Protect sensitive data - ensures that credentials, tokens, and query results are never transmitted in plain text
• Stay compliant - many organizations, regulations, and audits require HTTPS-only communication
• Remove inconsistencies - even if users try to connect via http://, they’re redirected to https://
• Harden authentication - secure cookies prevent hijacking over unencrypted channels

Tip

Browsers like Chrome may auto-upgrade some HTTP connections, but this isn’t guaranteed for all users or environments. Force HTTPS ensures the same security policy everywhere.

Turn on force HTTPS

1. You can enable Force HTTPS in one of the following ways:

   • during initial setup, in the Easy Config wizard when starting the application
   • later, in Settings -> Administration -> Server configuration
   • or, by setting the environment variable:

   CLOUDBEAVER_FORCE_HTTPS=true
   

   Info

   For details, see Server configuration.

2. Confirm that your proxy already has valid SSL certificates (see SSL certificates)

Once enabled, all requests over port 80 will be redirected to 443, and session cookies will be marked secure.

Warning

If SSL isn’t configured in the proxy, enabling force HTTPS will make the application unreachable.

Multiple server URLs

You can allow access from several domains instead of a single entry point. This improves SSO, migration, and high-availability scenarios.

For details, see Multiple server URLs.

Nginx configuration in CloudBeaver Community

In the Community Edition, you can configure Nginx manually to set up a web server in front of CloudBeaver.

If you prefer, you can configure HTTPS directly for the Jetty server. For details, see Jetty configuration.

1. Install Nginx on your server. Refer to the official Nginx documentation.

2. Add a proxy configuration:

   1. Open the main Nginx configuration file in a text editor.
   2. In your Nginx configuration file inside the http section, add the following:

         server {
            listen 80;
            server_name _;
            client_max_body_size 500M;
            location / {
               proxy_pass http://127.0.0.1:8978;
               proxy_set_header Host $host;
               proxy_set_header X-Real-IP $remote_addr;
               proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
               proxy_set_header X-Forwarded-Proto $scheme;
               proxy_http_version 1.1;
               proxy_set_header Upgrade $http_upgrade;
               proxy_set_header Connection "upgrade";
           }
       }
   

   To ensure the client’s real IP address is forwarded when using Nginx, add the forwardProxy:true parameter to your server configuration.

3. Apply the changes:

   • Reload the Nginx configuration.
   • Open CloudBeaver in your browser using http://127.0.0.1.