How to Self-Host CloudBeaver with Docker Compose

What Is CloudBeaver?

CloudBeaver is a web-based database IDE built on DBeaver, supporting 30+ database engines including PostgreSQL, MySQL, MariaDB, ClickHouse, Oracle, SQL Server, SQLite, MongoDB, and more. It provides a full SQL editor with autocomplete, visual query builder, ER diagrams, and data export. Unlike Adminer or phpMyAdmin, CloudBeaver is a professional-grade database IDE designed for teams. It’s open source under the Apache 2.0 license and available at cloudbeaver.io.

Updated March 2026: Verified with CloudBeaver 26.0.0 Docker image.

Prerequisites

• A Linux server (Ubuntu 22.04+ recommended)
• Docker and Docker Compose installed (guide)
• 1 GB of free RAM (minimum), 2 GB recommended
• 1 GB of free disk space

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  cloudbeaver:
    image: dbeaver/cloudbeaver:26.0.0
    container_name: cloudbeaver
    restart: unless-stopped
    ports:
      - "8978:8978"
    volumes:
      # CloudBeaver workspace — stores connections, configs, and user data
      - cloudbeaver_workspace:/opt/cloudbeaver/workspace
    environment:
      # JVM memory settings (adjust based on available RAM)
      CB_SERVER_MEMORY: 1024m
    networks:
      - cb-net

  # Example: PostgreSQL database (optional — remove if connecting to existing DBs)
  postgres:
    image: postgres:17-alpine
    container_name: cloudbeaver-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: cbuser
      POSTGRES_PASSWORD: change-this-password
      POSTGRES_DB: appdb
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U cbuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - cb-net

volumes:
  cloudbeaver_workspace:
  pg_data:

networks:
  cb-net:

Start the stack:

docker compose up -d

Initial Setup

1. Open http://your-server-ip:8978 in your browser
2. CloudBeaver presents a first-time setup wizard:
   • Server Name: Enter a name for this CloudBeaver instance
   • Admin Credentials: Create an administrator username and password
   • Server Configuration: Keep defaults or adjust session timeout
3. Click Finish to complete setup
4. Log in with the admin credentials you just created

Adding a Database Connection

1. Click the + button in the top navigation bar
2. Select your database type (PostgreSQL, MySQL, etc.)
3. Enter connection details:
   • Host: postgres (Docker service name) or the IP of your external database
   • Port: 5432 (PostgreSQL default)
   • Database: appdb
   • Username/Password: your database credentials
4. Click Test Connection to verify, then Create

Configuration

User Management

CloudBeaver Community Edition supports local user accounts:

1. Go to Administration > Users
2. Create users with specific connection access
3. Assign connections per user — users only see databases they’re authorized for

Connection Templates

Pre-configure database connections by editing the workspace config. Mount a custom initial-data-sources.conf:

volumes:
  - ./initial-data-sources.conf:/opt/cloudbeaver/conf/initial-data-sources.conf:ro

JVM Tuning

Adjust memory allocation based on your workload:

environment:
  CB_SERVER_MEMORY: 2048m

Workload	Recommended Memory
Light (1-3 connections, casual use)	512m
Medium (5-10 connections, regular queries)	1024m
Heavy (10+ connections, large result sets)	2048m

Supported Database Drivers

Database	Built-in	Notes
PostgreSQL	Yes	Full support including extensions
MySQL / MariaDB	Yes	Full support
ClickHouse	Yes	Analytical queries
SQLite	Yes	File-based databases
SQL Server	Yes	JDBC driver included
Oracle	Yes	JDBC driver included
MongoDB	Yes	Document browser
H2	Yes	Embedded database
DuckDB	Yes	Analytical queries

Reverse Proxy

For HTTPS access behind a reverse proxy:

• Forward Hostname: cloudbeaver
• Forward Port: 8978
• Enable WebSocket support (required for CloudBeaver’s real-time features)

For Nginx, add WebSocket headers:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

For detailed setup, see Reverse Proxy Setup.

Backup

Back up the CloudBeaver workspace volume, which contains all connections, user accounts, and settings:

docker run --rm -v cloudbeaver_workspace:/data -v $(pwd):/backup alpine \
  tar czf /backup/cloudbeaver-backup-$(date +%Y%m%d).tar.gz -C /data .

Back up your databases separately using their native tools. For a comprehensive approach, see Backup Strategy.

Troubleshooting

CloudBeaver shows “Server is not available”

Symptom: Web UI loads but shows a connection error. Fix: The JVM may need more memory. Increase CB_SERVER_MEMORY to 2048m. Check logs: docker logs cloudbeaver. First startup takes 30-60 seconds for JVM initialization.

Cannot connect to database on the same Docker network

Symptom: Connection test fails with “Connection refused.” Fix: Use the Docker service name (e.g., postgres) as the hostname, not localhost. Ensure both services are on the same Docker network.

Query results are slow or truncated

Symptom: Large result sets load slowly or get cut off. Fix: In Administration > Server Configuration, increase the result set row limit. Default is 200 rows per query. Also increase CB_SERVER_MEMORY if handling large datasets.

Resource Requirements

• RAM: ~300-500 MB idle, 500 MB-1 GB under active query load
• CPU: Medium (JVM-based)
• Disk: ~500 MB for the Docker image + workspace data

Verdict

CloudBeaver is the best choice for teams that need a full-featured database IDE accessible from a browser. Its SQL editor with autocomplete, ER diagrams, and multi-database support put it in a different class than simpler tools. For quick, lightweight database access, Adminer is better — single container, ~20 MB RAM. For MySQL-only environments, phpMyAdmin has deeper MySQL-specific features. CloudBeaver is the right tool when you need a DBeaver-quality experience in a self-hosted web application.

Frequently Asked Questions

How does CloudBeaver compare to phpMyAdmin and Adminer?

CloudBeaver is a full database IDE with SQL autocomplete, ER diagrams, and multi-database support. Adminer is a lightweight single-file database manager (~20 MB RAM) for quick access. phpMyAdmin is MySQL/MariaDB-specific with deeper MySQL features. Choose CloudBeaver when you need a DBeaver-quality experience in the browser; Adminer for lightweight, multi-database access; phpMyAdmin for MySQL-specific administration.

Does CloudBeaver support MongoDB?

Yes. CloudBeaver includes a MongoDB driver with a document browser for viewing and editing collections. It’s not as feature-rich as a dedicated MongoDB client, but it provides basic browsing, querying, and document editing capabilities within the same interface you use for SQL databases.

Can multiple users share CloudBeaver?

Yes. The Community Edition supports local user accounts with per-connection access control. Create users in Administration → Users and assign specific database connections to each user. Users only see databases they’re authorized to access. The Enterprise Edition adds LDAP/SSO integration and team features.

Why does CloudBeaver use so much memory?

CloudBeaver runs on the JVM (Java), which requires a dedicated heap allocation. The default CB_SERVER_MEMORY setting determines the JVM heap size. For light usage with 1-3 connections, 512 MB is sufficient. For heavier workloads with large result sets, increase to 1-2 GB. The JVM overhead is the trade-off for CloudBeaver’s rich feature set.

Can I connect to databases on other servers?

Yes. Enter the database server’s IP address or hostname instead of a Docker service name when creating a connection. CloudBeaver can connect to any network-accessible database server. If the database is on a remote server, ensure firewall rules allow the connection on the database port (e.g., 5432 for PostgreSQL, 3306 for MySQL).

Is CloudBeaver open source?

Yes. The Community Edition is open-source under the Apache 2.0 license. There’s also a paid Enterprise Edition with additional features like LDAP/SSO, advanced security policies, and query auditing. All core database management features — SQL editor, ER diagrams, data export — are available in the free Community Edition.

Related

• CloudBeaver vs Adminer: Which Should You Self-Host?
• Best Self-Hosted Database Management Tools
• pgAdmin vs Adminer
• How to Self-Host Adminer
• How to Self-Host pgAdmin
• How to Self-Host phpMyAdmin
• Docker Compose Basics
• Reverse Proxy Setup