Skip to content

Docker compose

Note

This deployment method is available in the Enterprise edition only.

Use Docker Compose to deploy CloudBeaver Enterprise on Ubuntu, macOS, or Windows.

Info

For advanced configurations, such as system requirements, ssl configuration, or podman requirements, refer to the Advanced settings guide.

Note

CloudBeaver Enterprise's Docker Compose setup includes a pre-configured web service.

Required network access

To ensure that CloudBeaver can be deployed and updated successfully, make sure the server has outbound access to specific websites. These domains are required for downloading Docker images, validating licenses, updating components, and resolving database drivers.

Required domains

Add the following domains to your firewall or proxy allowlist:

Warning

If access to any of these sites is restricted, you may see errors when updating, downloading components, or validating the license.

Domain Purpose
hub.docker.com Pull Docker images from Docker Hub
Docker image mirrors Content delivery domains used for image layers. See the full allowlist.
dbeaver.com License validation
databases.team Let's Encrypt certificates for custom domains. Learn more on Domain Manager
Maven Central and repositories Required to download some JDBC drivers we don’t bundle with the product (see Maven Central)

Important

The cloudbeaver container must have outbound access to all required domains.

Check access from the command line

Before starting the containers, make sure your environment can access essential external services:

ping hub.docker.com
curl -I https://dbeaver.com

If you already have CloudBeaver running, you can also verify network access from inside a container.

If you're using Docker:

# List containers
docker ps

# Open a shell in the cloudbeaver container
docker exec -it <cloudbeaver_container_id> bash

# Test connectivity inside the container
ping hub.docker.com
curl -I https://dbeaver.com

# Check HTTPS certificate retrieval (useful if using a Domain Manager)
openssl s_client -connect <your-domain>:443 -servername <your-domain>

Tip

If you're having trouble resolving hostnames inside containers, review Docker network settings. DNS issues can prevent access to required domains even if outbound connectivity is available.

If you're using Kubernetes:

# List pods
kubectl get pods

# Open a shell in the cloudbeaver pod
kubectl exec --stdin --tty <cloudbeaver_pod_name> -- /bin/bash

# Test connectivity inside the pod
ping hub.docker.com
curl -I https://dbeaver.com

# Check HTTPS certificate retrieval (useful if using a Domain Manager)
openssl s_client -connect <your-domain>:443 -servername <your-domain>

If DNS resolution fails inside a pod, check your Kubernetes DNS configuration. Misconfigured DNS can block access even when the network itself is available.

Important

Docker and Kubernetes environments require access to several domains for authentication, image pulls, and updates. Make sure all required domains are accessible from inside your containers or pods. You can test any domain from the allowlist using:

curl -I https://<domain>

Deploying with host networking

By default, CloudBeaver Enterprise runs using docker-compose.yml, which uses Docker's bridge network. If you need containers to run directly on the host network (for example, to bind CloudBeaver to a specific network interface), use docker-compose-host.yml.

Installation on Ubuntu

Required tools setup

Configuring and starting CloudBeaver Enterprise

  1. Clone the deployment repository:

    git clone https://github.com/dbeaver/cloudbeaver-deploy
    

  2. Navigate to the CloudBeaver deploy directory:

    cd cloudbeaver-deploy
    

  3. Set up the .env file as described here.

    Important

    You must change the default password in the .env file before starting the cluster. Set CLOUDBEAVER_DB_PASSWORD to a strong password of your choice.

  4. Start the cluster:

    docker compose up -d
    

  5. Access CloudBeaver Enterprise at http://<server-ip>.

    Tip

    Replace <server-ip> with your server’s actual IP address. You can configure the domain during the initial setup. For more details, see Domain Manager.

  6. Wait for PostgreSQL and CloudBeaver to become ready. The proxy may briefly return a startup error, such as HTTP 502, while the services initialize. Inspect the service logs if readiness doesn't complete within your operational timeout.

  7. Complete initial administrator setup and license activation in the administration interface.

Installation on macOS

Required tools setup

  • Install Docker Desktop for macOS from Docker website. Make sure Docker Desktop is running before proceeding.
  • Install Docker Compose if it’s not bundled with Docker Desktop:

    brew install docker-compose
    
  • Install Git if it’s not already installed:

    brew install git
    
  • Verify the installation:

    docker --version
    docker-compose --version
    git --version
    

Configuring and starting CloudBeaver Enterprise

  1. Clone the deployment repository:

    git clone https://github.com/dbeaver/cloudbeaver-deploy
    
  2. Navigate to the CloudBeaver deploy directory:

    cd cloudbeaver-deploy
    
  3. Set up the .env file as described here.

    Important

    You must change the default password in the .env file before starting the cluster. Set CLOUDBEAVER_DB_PASSWORD to a strong password of your choice.

  4. Start the cluster:

    docker-compose up -d
    
  5. Access CloudBeaver Enterprise at http://<server-ip>.

    Tip

    Replace <server-ip> with your server’s actual IP address. You can configure the domain during the initial setup. For more details, see Domain Manager.

  6. Wait for PostgreSQL and CloudBeaver to become ready. The proxy may briefly return a startup error, such as HTTP 502, while the services initialize. Inspect the service logs if readiness doesn't complete within your operational timeout.

  7. Complete initial administrator setup and license activation in the administration interface.

Installation on Windows

Required tools setup

  • Install Docker Desktop.
  • Install Git.

Tip

Supported on Windows 10 and 11. Docker Desktop doesn’t work on Windows Server.

Configuring and starting CloudBeaver Enterprise

  1. Clone the deployment repository:

    git clone https://github.com/dbeaver/cloudbeaver-deploy
    
  2. Navigate to the deployment directory:

    cd cloudbeaver-deploy
    
  3. Use .env.example as the template for the active .env file.

  4. Set up the active .env file as described here.

    Important

    You must change the default password in the .env file before starting the cluster. Set CLOUDBEAVER_DB_PASSWORD to a strong password of your choice.

  5. Start the cluster:

    docker-compose up -d
    
  6. Access CloudBeaver Enterprise at http://<server-ip>.

    Tip

    Replace <server-ip> with your server’s actual IP address. You can configure the domain during the initial setup. For more details, see Domain Manager.

  7. Wait for PostgreSQL and CloudBeaver to become ready. The proxy may briefly return a startup error, such as HTTP 502, while the services initialize. Inspect the service logs if readiness doesn't complete within your operational timeout.

  8. Complete initial administrator setup and license activation in the administration interface.

Update CloudBeaver Enterprise

For detailed update instructions, see Update version.

Environment file configuration

The checked-in .env.example file is the template. Copy it to .env, then edit the active .env file used by Compose. Set CLOUDBEAVER_DB_PASSWORD to a strong, non-empty value before starting the deployment.

Use the exact CLOUDBEAVER_VERSION_TAG supplied in the checked-in template for this deployment package. That value is authoritative even if surrounding documentation mentions another version.

The provided Compose configuration doesn't automate administrator setup or mount a license file. Complete initial setup and license activation in the administration interface before relying on functional backup and restore checks.

After the endpoint responds over HTTPS, manually verify hostname and trust-chain validation from a production-equivalent client.

Docker Compose variables

Variable Description Default value
IMAGE_SOURCE Defines the primary source of the Docker image. dbeaver
PODMAN_IMAGE_SOURCE Sets the Podman image source. docker.io/dbeaver
COMPOSE_PROJECT_NAME Defines the project name for Docker Compose. dbeaver
CLOUDBEAVER_VERSION_TAG Specifies the exact CloudBeaver image tag supplied by the deployment template. See Docker tags. Template value
REPLICA_COUNT_EE Specifies the number of replicas for Enterprise Edition. See Docker Service Scale Documentation. 1
PROXY_TYPE Specifies the proxy server to use. Supported values: nginx, haproxy. For more details on configuring proxy server, see the Proxy configuration. nginx

CloudBeaver configuration variables

For the full list of CloudBeaver configuration variables and their descriptions, see Server configuration.