This article provides a guide demonstrating how to deploy CloudBeaver on Ubuntu VPS.

Table of Contents

What is CloudBeaver?

CloudBeaver is a web-based database management platform from the developers of DBeaver. It provides a browser-accessible interface for working with PostgreSQL, MariaDB, MySQL, SQL Server, Oracle, and numerous other databases without requiring users to install a desktop database client.

For a VPS deployment, the cleanest approach is to run CloudBeaver Community Edition in Docker, place Nginx in front of it as a reverse proxy, and secure the public interface with a Let’s Encrypt SSL certificate.

As of September 2026, the current stable CloudBeaver release series is 26.2, with CloudBeaver 26.2.0 released August 31, 2026. DBeaver publishes the Community Edition as the official dbeaver/cloudbeaver Docker image.

This guide uses:

Ubuntu 24.04 LTS
CloudBeaver Community Edition
Docker Engine and Docker Compose
Nginx
Let’s Encrypt / Certbot
A persistent CloudBeaver workspace
A domain such as db.example.com

The same procedure is also suitable for Ubuntu 22.04.

CloudBeaver VPS requirements

CloudBeaver itself is not particularly resource-intensive for a small deployment, although resource requirements increase with the number of concurrent users and database connections.

A reasonable starting configuration is:

Resource	Recommended
CPU	2 vCPU
RAM	2-4 GB
Storage	20+ GB SSD/NVMe
OS	Ubuntu 24.04 LTS
Network	Public IPv4/IPv6
Domain	Recommended
Ports	22, 80, 443

For production use, 4 GB RAM or more is preferable.

CloudBeaver normally listens internally on TCP port 8978. The official documentation uses this port for Docker deployments.

We will not expose port 8978 publicly. Instead:

Internet
   |
   | HTTPS :443
   v
+-------------------+
|      Nginx        |
| Reverse Proxy     |
+-------------------+
         |
         | 127.0.0.1:8978
         v
+-------------------+
|    CloudBeaver    |
|      Docker       |
+-------------------+
         |
         +---- PostgreSQL
         +---- MariaDB/MySQL
         +---- SQL Server
         +---- Other databases

This is safer than exposing CloudBeaver’s Jetty application server directly to the Internet.

Compare Ubuntu VPS Plans

KVM-SSD-1

KVM-SSD-8

KVM-SSD-16

KVM-SSD-32

CPU

1 Core

2 Cores

4 Cores

8 Cores

Memory

1 GB

8 GB

16 GB

32 GB

Storage

16 GB NVMe

128 GB NVMe

256 GB NVMe

512 GB NVMe

Bandwidth

1 TB

4 TB

8 TB

16 TB

Network

1 Gbps

Delivery Time

⏱️ Instant

Location

US/EU/APAC

Price

$7.58*

$39.50*

$79.40*

$151.22*

View All

Order

KVM-SSD-1

$7.58*

CPU 1 Core

Memory 1 GB

Storage 16 GB NVMe

Bandwidth 1 TB

Network 1 Gbps

Delivery Time ⏱️ Instant

Location US/EU/APAC

Order KVM-SSD-1

KVM-SSD-8

$39.50*

CPU 2 Cores

Memory 8 GB

Storage 128 GB NVMe

Bandwidth 4 TB

Network 1 Gbps

Delivery Time ⏱️ Instant

Location US/EU/APAC

Order KVM-SSD-8

KVM-SSD-16

$79.40*

CPU 4 Cores

Memory 16 GB

Storage 256 GB NVMe

Bandwidth 8 TB

Network 1 Gbps

Delivery Time ⏱️ Instant

Location US/EU/APAC

Order KVM-SSD-16

KVM-SSD-32

$151.22*

CPU 8 Cores

Memory 32 GB

Storage 512 GB NVMe

Bandwidth 16 TB

Network 1 Gbps

Delivery Time ⏱️ Instant

Location US/EU/APAC

Order KVM-SSD-32

How to Deploy CloudBeaver on Ubuntu VPS

To deploy CloudBeaver on Ubuntu VPS, follow the steps outlined below:

Connect to the Ubuntu VPS

Connect to the server over SSH:
```
ssh root@SERVER_IP
```
Or, preferably, use a sudo-enabled administrative account:
```
ssh username@SERVER_IP
```
Become root if necessary:
```
sudo -i
```
Confirm the Ubuntu version:
```
cat /etc/os-release
```
For Ubuntu 24.04 you should see something similar to:
```
NAME="Ubuntu"
VERSION="24.04 LTS (Noble Numbat)"
VERSION_CODENAME=noble
```
Update Ubuntu

Install the latest package updates:
```
apt update
apt upgrade -y
```
Install several useful utilities:
```
apt install -y \
    ca-certificates \
    curl \
    gnupg \
    git \
    unzip \
    nano \
    ufw
```
If the kernel or important system libraries were updated, reboot:

See Also: How to Download and Migrate a Weebly Site to Rad Web Hosting
```
reboot
```
Then reconnect over SSH.
Configure the Server Hostname

Although not mandatory, assigning the VPS an appropriate hostname is recommended.

For example:
```
hostnamectl set-hostname cloudbeaver.example.com
```
Verify:
```
hostnamectl
```
Configure DNS

Create an A record pointing your desired CloudBeaver hostname to the VPS.

For example:
```
db.example.com.    A    203.0.113.25
```
If IPv6 is configured, you can also add:
```
db.example.com.    AAAA    2001:db8::25
```
Check DNS resolution:
```
dig +short db.example.com
```
or:
```
getent hosts db.example.com
```
Do not request the Let’s Encrypt certificate until DNS resolves to the VPS.

Install Docker Engine

Docker officially supports Ubuntu 24.04 and Ubuntu 22.04. The recommended production method is installing Docker Engine from Docker’s official APT repository rather than using Ubuntu’s older docker.io package.

First remove potentially conflicting packages:

apt remove -y docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc 2>/dev/null || true

Create the Docker key directory:

install -m 0755 -d /etc/apt/keyrings

Download Docker’s signing key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
    -o /etc/apt/keyrings/docker.asc

Set appropriate permissions:

chmod a+r /etc/apt/keyrings/docker.asc

Add the Docker repository:

cat > /etc/apt/sources.list.d/docker.sources <

Update APT:

apt update

Install Docker:

apt install -y \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-buildx-plugin \
    docker-compose-plugin

These are the packages currently recommended by Docker for Ubuntu installations.

Enable Docker

Enable Docker at boot:

systemctl enable --now docker

Check its status:

systemctl status docker --no-pager

Check the installed version:

docker --version

And Docker Compose:

docker compose version

Test Docker:

docker run --rm hello-world

You should receive:

Hello from Docker!

Create the CloudBeaver directory structure

We’ll keep the deployment underneath:
```
/opt/cloudbeaver/
```
Create the directories:
```
mkdir -p /opt/cloudbeaver/workspace
cd /opt/cloudbeaver
```
CloudBeaver’s workspace needs to survive container recreation and upgrades.

The official image expects its persistent workspace at:
```
/opt/cloudbeaver/workspace
```
inside the container.Create a Docker Compose configuration
Create:
```
nano /opt/cloudbeaver/docker-compose.yml
```
Add:
```
services:

  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver

    restart: unless-stopped

    ports:
      - "127.0.0.1:8978:8978"

    volumes:
      - ./workspace:/opt/cloudbeaver/workspace

    environment:
      JAVA_OPTS: "-Xms512m -Xmx2048m"
```
Save and exit.

This configuration does several important things.

restart: unless-stopped

CloudBeaver automatically starts again after:
- server reboot
- Docker restart
- unexpected container failure
127.0.0.1:8978:8978

This is intentionally different from:

See Also: How to Setup a Load-Balanced Apache Cluster (6 Step Quick-Start Guide)
```
8978:8978
```
Binding to:
```
127.0.0.1
```
means CloudBeaver cannot be reached directly from the Internet.

Only Nginx on the local server can reach it.

Workspace volume

This:
```
./workspace:/opt/cloudbeaver/workspace
```
preserves:
- server configuration
- users
- connection configuration
- authentication configuration
- workspace metadata
CloudBeaver’s documentation specifically recommends persisting the workspace when using Docker.
Optional: Pin CloudBeaver to a specific version

For production infrastructure, you may prefer not to use:
```
image: dbeaver/cloudbeaver:latest
```
Instead you can pin the container to a tested release.

For example:
```
image: dbeaver/cloudbeaver:26.2.0
```
CloudBeaver’s release system supports:
```
latest
ea
specific version tags
major-version tags
```
The latest tag tracks the current stable version, whereas ea tracks Early Access builds. GitHub

For production systems, avoid:
```
:ea
```
unless you specifically intend to test prerelease software.

Start CloudBeaver

From:

cd /opt/cloudbeaver

pull the image:

docker compose pull

Start CloudBeaver:

docker compose up -d

Check the container:

docker ps

You should see something similar to:

CONTAINER ID   IMAGE                         STATUS
xxxxxxxxxxxx   dbeaver/cloudbeaver:latest    Up

Check the CloudBeaver logs

Run:
```
docker logs cloudbeaver
```
For live logs:
```
docker logs -f cloudbeaver
```
Press:
```
Ctrl+C
```
to stop following the logs.

You can also use Compose:
```
docker compose logs -f cloudbeaver
```
Test CloudBeaver locally

Because we deliberately bound the service to localhost, test from the VPS:
```
curl -I http://127.0.0.1:8978/
```
You should receive an HTTP response.

Another useful test is:
```
ss -lntp | grep 8978
```
You should see:
```
127.0.0.1:8978
```
rather than:
```
0.0.0.0:8978
```
That confirms CloudBeaver is not publicly exposed.

Install Nginx

Install Nginx:

apt install -y nginx

Enable it:

systemctl enable --now nginx

Check:

systemctl status nginx --no-pager

The CloudBeaver documentation specifically supports placing Nginx in front of Community Edition and provides an Nginx reverse-proxy example for port 8978.

Create the CloudBeaver Nginx virtual host

Assume the hostname will be:

db.example.com

Create:

nano /etc/nginx/sites-available/cloudbeaver.conf

Add:

server {
    listen 80;
    listen [::]:80;

    server_name db.example.com;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:8978;

        proxy_http_version 1.1;

        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

The Upgrade and Connection headers are important because CloudBeaver uses WebSockets for some functionality. DBeaver explicitly notes that socket support should be preserved through the proxy. DBeaver

Enable the configuration:

ln -s /etc/nginx/sites-available/cloudbeaver.conf \
      /etc/nginx/sites-enabled/cloudbeaver.conf

Optionally remove the default site:

rm -f /etc/nginx/sites-enabled/default

Test the Nginx configuration

Run:

nginx -t

You should see:

syntax is ok
test is successful

Reload Nginx:

systemctl reload nginx

Configure the Ubuntu firewall

If you use UFW, first make sure SSH remains allowed:
```
ufw allow OpenSSH
```
Allow HTTP:
```
ufw allow 80/tcp
```
Allow HTTPS:
```
ufw allow 443/tcp
```
Enable UFW:
```
ufw enable
```
Check:
```
ufw status
```
Expected:
```
22/tcp     ALLOW
80/tcp     ALLOW
443/tcp    ALLOW
```
You do not need:
```
ufw allow 8978
```
because CloudBeaver should remain behind Nginx.

Important Docker firewall note

Docker modifies host firewall rules itself, and published container ports can bypass some UFW expectations. Docker explicitly warns administrators about this behavior.

That is another reason we used:
```
127.0.0.1:8978:8978
```
rather than:
```
8978:8978
```
The service is restricted at the actual socket binding rather than relying only on UFW.
Test CloudBeaver through Nginx

Open:
```
http://db.example.com
```
You should now see the CloudBeaver setup interface.

Do not perform a production setup over HTTP yet if the server is publicly accessible.

Let’s enable HTTPS first.
Install Certbot

Certbot currently recommends its Snap package for most Linux/Nginx deployments.

Ensure Snap is available:
```
apt install -y snapd
```
Install Certbot:
```
snap install --classic certbot
```
Create the command symlink:
```
ln -sf /snap/bin/certbot /usr/local/bin/certbot
```
Verify:
```
certbot --version
```
Obtain a Let’s Encrypt certificate

Run:
```
certbot --nginx -d db.example.com
```
Certbot will:
1. Validate the domain.
2. Obtain the certificate.
3. Configure Nginx.
4. Enable HTTPS.
5. Optionally redirect HTTP to HTTPS.
When asked whether to redirect HTTP to HTTPS, select the redirect option.

Certbot’s Nginx integration is specifically designed to obtain and install the certificate automatically.
Test HTTPS

Visit:
```
https://db.example.com
```
You should now see the CloudBeaver interface over HTTPS.

You can verify from the shell:
```
curl -I https://db.example.com
```
Verify certificate renewal

Let’s Encrypt certificates are automatically renewed by Certbot’s timer.

Test the process:
```
certbot renew --dry-run
```
Certbot documents renew --dry-run as the standard test for automatic certificate renewal.

Check the timer:
```
systemctl list-timers | grep certbot
```
Depending on the Snap configuration you may instead see its corresponding Snap timer.
Complete the CloudBeaver initial setup wizard

Navigate to:

See Also: Getting Started With WHMCS: Features, Benefits, and Setup Guide
```
https://db.example.com
```
The first-run wizard will configure the CloudBeaver server.

You will generally be asked to configure options such as:
- server name
- administrative user
- administrator password
- anonymous access
- user authentication
- server URL
For a production installation, I recommend:
```
Server URL:
https://db.example.com
```
Disable anonymous database access unless there is a specific reason to provide it.

Create a strong administrator password.

For example, generate one with:
```
openssl rand -base64 32
```
Do not reuse the VPS root password.
Log into CloudBeaver

Once initialization is complete, log into:
```
https://db.example.com
```
with the administrator credentials created during setup.

The main CloudBeaver interface should appear.

Add a PostgreSQL database connection

As an example, suppose you have:

Database server: 192.168.4.50
Port:            5432
Database:        production
Username:        cloudbeaver

From CloudBeaver:

Administration
    → Connections
    → New Connection

Select:

PostgreSQL

Enter:

Host:       192.168.4.50
Port:       5432
Database:   production
Username:   cloudbeaver
Password:   ********

Click:

Test

Then:

Create

Connecting to MariaDB or MySQL

For MariaDB/MySQL, use:
```
Host: database.example.internal
Port: 3306
Database: database_name
Username: cloudbeaver
Password: ********
```
Ideally, create a dedicated database user instead of giving CloudBeaver root.

For example:
```
CREATE USER 'cloudbeaver'@'CLOUDBEAVER_IP'
IDENTIFIED BY 'VERY_STRONG_PASSWORD';
```
Then assign only the permissions actually needed.

For read-only access:
```
GRANT SELECT, SHOW VIEW
ON exampledb.*
TO 'cloudbeaver'@'CLOUDBEAVER_IP';
```
For administrative work you can grant additional privileges as appropriate.
Do not expose database ports unnecessarily

If CloudBeaver and the database live within the same provider/network, connect them over:
- private VLAN
- private IPv4
- WireGuard VPN
- internal routed network
- localhost, if running on the same VPS
instead of exposing database services directly to the Internet.

For example:
```
CloudBeaver
192.168.4.20

PostgreSQL
192.168.4.30
```
would be preferable to connecting CloudBeaver to PostgreSQL over a public address.
Allow CloudBeaver through the database firewall

For PostgreSQL:
```
ufw allow from CLOUDBEAVER_IP to any port 5432 proto tcp
```
For MariaDB/MySQL:
```
ufw allow from CLOUDBEAVER_IP to any port 3306 proto tcp
```
Do not use:
```
ufw allow 3306
```
or:
```
ufw allow 5432
```
unless there is a legitimate reason the databases must be globally accessible.
Connecting to a database running on the same VPS

There is one important Docker networking consideration.

Inside the CloudBeaver container:
```
127.0.0.1
```
refers to the container itself, not the Ubuntu host.

Therefore a database listening at:

See Also: 🚀 How to Install and Configure Node Exporter on Debian VPS
```
127.0.0.1:3306
```
on Ubuntu cannot automatically be reached as:
```
localhost:3306
```
from CloudBeaver.

One option is adding the Docker host gateway.

Modify:
```
nano /opt/cloudbeaver/docker-compose.yml
```
Add:
```
extra_hosts:
  - "host.docker.internal:host-gateway"
```
The complete service becomes:
```
services:

  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver

    restart: unless-stopped

    ports:
      - "127.0.0.1:8978:8978"

    volumes:
      - ./workspace:/opt/cloudbeaver/workspace

    extra_hosts:
      - "host.docker.internal:host-gateway"

    environment:
      JAVA_OPTS: "-Xms512m -Xmx2048m"
```
Apply:
```
cd /opt/cloudbeaver
docker compose up -d
```
CloudBeaver can then attempt to reach the Ubuntu host using:
```
host.docker.internal
```
Your database service must also listen on an address accessible from Docker.
Verify CloudBeaver container networking

Enter the container:
```
docker exec -it cloudbeaver bash
```
You can inspect name resolution:
```
getent hosts host.docker.internal
```
Exit:
```
exit
```
You can also inspect the Docker network:
```
docker inspect cloudbeaver
```
Adjust CloudBeaver Java memory

CloudBeaver supports setting JVM parameters through:
```
JAVA_OPTS
```
including Java heap limits.

For a 2 GB VPS you might use:
```
JAVA_OPTS: "-Xms256m -Xmx1024m"
```
For a 4 GB VPS:
```
JAVA_OPTS: "-Xms512m -Xmx2048m"
```
For an 8 GB VPS:
```
JAVA_OPTS: "-Xms1024m -Xmx4096m"
```
Do not allocate the entire server memory to Java because Ubuntu, Docker, Nginx, and database drivers also need RAM.

After changing it:
```
docker compose up -d
```
Check CloudBeaver resource usage

Docker provides an easy live resource monitor:
```
docker stats cloudbeaver
```
You can see:
```
CPU %
MEM USAGE
MEM %
NETWORK I/O
BLOCK I/O
```
Press:
```
Ctrl+C
```
when finished.
View CloudBeaver logs

Recent logs:
```
docker logs --tail 100 cloudbeaver
```
Live logs:
```
docker logs -f cloudbeaver
```
Logs since a specific period:
```
docker logs --since 30m cloudbeaver
```
CloudBeaver startup failures, JDBC driver problems, and authentication errors often appear here.

View Nginx logs

Access log:

tail -f /var/log/nginx/access.log

Error log:

tail -f /var/log/nginx/error.log

For example, an Nginx:

502 Bad Gateway

typically means Nginx cannot reach:

127.0.0.1:8978

Check:

curl http://127.0.0.1:8978

and:

docker ps

Restart CloudBeaver

Restart only the application:

cd /opt/cloudbeaver
docker compose restart cloudbeaver

Or:

docker restart cloudbeaver

Stop CloudBeaver

Run:

cd /opt/cloudbeaver
docker compose down

The workspace remains intact because it lives in:

/opt/cloudbeaver/workspace

Restart:

docker compose up -d

Back up CloudBeaver

The most important CloudBeaver directory to back up is:
```
/opt/cloudbeaver/workspace
```
DBeaver recommends backing up the workspace before upgrades.

A simple backup procedure is:

See Also: 🚀 How to Deploy CapRover on Ubuntu VPS
```
cd /opt/cloudbeaver
docker compose stop
```
Create the backup:
```
tar -czf /root/cloudbeaver-workspace-$(date +%F).tar.gz workspace/
```
Restart:
```
docker compose start
```
Check:
```
ls -lh /root/cloudbeaver-workspace-*.tar.gz
```
For production, include this directory in your normal VPS backup system.
Upgrade CloudBeaver

Before upgrading, back up the workspace.
```
cd /opt/cloudbeaver
docker compose stop
```
Backup:
```
tar -czf /root/cloudbeaver-workspace-$(date +%F-%H%M).tar.gz workspace/
```
Restart:
```
docker compose start
```
Pull the new image:
```
docker compose pull
```
Recreate the container:
```
docker compose up -d
```
Check:
```
docker ps
```
Then:
```
docker logs --tail 100 cloudbeaver
```
DBeaver’s documented Docker upgrade workflow similarly consists of backing up the workspace, pulling the new image, and recreating the deployment. Downgrades should not be assumed to be supported.
Remove old Docker images

After several upgrades you may accumulate unused images.

Check:
```
docker images
```
Clean unused images:
```
docker image prune
```
Or:
```
docker image prune -a
```
Be more cautious with -a, because it removes every image not currently referenced by a container.
Production security recommendations

Because CloudBeaver provides direct access to databases, treat it as an administrative system rather than a normal website.

At minimum:

Require HTTPS

Only expose:
```
https://db.example.com
```
Keep port 8978 private

Verify:
```
ss -lntp | grep 8978
```
Expected:
```
127.0.0.1:8978
```
Restrict database privileges

Use individual database accounts or constrained service accounts.

Avoid giving every CloudBeaver user database administrator credentials.

Use private networking

Prefer:
```
CloudBeaver → private network → database
```
over:
```
CloudBeaver → Internet → database
```
Disable unnecessary anonymous functionality

Database management applications generally should require authentication.

Keep CloudBeaver updated

Check the release before periodically performing:
```
docker compose pull
docker compose up -d
```
CloudBeaver uses quarterly stable releases alongside more frequent Early Access builds.

Keep Ubuntu updated

Run periodically:
```
apt update
apt upgrade -y
```
Back up the workspace

Back up:
```
/opt/cloudbeaver/workspace
```
regularly.

Optional: restrict CloudBeaver to specific source IPs

For a company-only administration portal, you could restrict access at Nginx.

For example:

location / {

    allow 203.0.113.100;
    allow 198.51.100.0/24;
    deny all;

    proxy_pass http://127.0.0.1:8978;

    proxy_http_version 1.1;

    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_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

Then:

nginx -t
systemctl reload nginx

This is particularly useful if CloudBeaver is purely an internal administrative tool.

Optional: protect CloudBeaver with HTTP Basic Authentication

You can place another authentication layer in front of CloudBeaver.

See Also: How to Host Your Own Mastodon Server on a VPS (5 Minute Quick-Start Guide)

Install:
```
apt install -y apache2-utils
```
Create a user:
```
htpasswd -c /etc/nginx/.cloudbeaver-users admin
```
Then inside the Nginx location / section add:
```
auth_basic "Restricted Database Administration";
auth_basic_user_file /etc/nginx/.cloudbeaver-users;
```
Test:
```
nginx -t
```
Reload:
```
systemctl reload nginx
```
Users must then pass Nginx authentication before they can even reach CloudBeaver’s login screen.
Troubleshooting: CloudBeaver container won’t start

Check:
```
docker ps -a
```
Then:
```
docker logs cloudbeaver
```
Check Compose:
```
cd /opt/cloudbeaver
docker compose config
```
A valid configuration should be displayed without errors.

Troubleshooting: 502 Bad Gateway

If you see:

502 Bad Gateway

check whether CloudBeaver is running:

docker ps

Then:

curl -v http://127.0.0.1:8978

Check the listening socket:

ss -lntp | grep 8978

Restart:

docker restart cloudbeaver

Check:

tail -100 /var/log/nginx/error.log

Troubleshooting: database connection timeout

A timeout usually indicates networking rather than credentials.

From Ubuntu, test:
```
nc -vz DATABASE_IP 3306
```
for MariaDB/MySQL or:
```
nc -vz DATABASE_IP 5432
```
for PostgreSQL.

If nc is missing:
```
apt install -y netcat-openbsd
```
Then test from inside the CloudBeaver container if necessary:
```
docker exec -it cloudbeaver bash
```
The important distinction is:
```
VPS can reach database
```
versus:
```
Docker container can reach database
```
These aren’t necessarily the same thing.
Troubleshooting: connection refused

A response such as:
```
Connection refused
```
usually means the remote host is reachable but nothing is accepting the connection at that address/port.

For PostgreSQL check:
```
ss -lntp | grep 5432
```
For MariaDB/MySQL:
```
ss -lntp | grep 3306
```
You may also need to adjust:
```
postgresql.conf
pg_hba.conf
```
or:
```
mysqld bind-address
```
depending on the database.
Troubleshooting: CloudBeaver cannot access localhost database

Remember that:
```
localhost
```
inside CloudBeaver means the container.

Try:
```
host.docker.internal
```
if you configured:
```
extra_hosts:
  - "host.docker.internal:host-gateway"
```
You may also need to make the host database listen on the Docker bridge interface rather than only:
```
127.0.0.1
```

Troubleshooting: CloudBeaver works by IP but not domain

Check DNS:

dig +short db.example.com

Check Nginx:

nginx -t

Check the configured host:

grep -R "server_name" /etc/nginx/sites-enabled/

Check firewall:

ufw status

And test:

curl -I http://db.example.com

Troubleshooting WebSockets

If login works but some real-time functionality or SSO features behave unexpectedly, verify these directives remain in Nginx:
```
proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
```
CloudBeaver’s documentation notes that sockets are used for real-time functionality and SSO, and recommends preserving WebSocket connectivity through the proxy.

Final Docker Compose file

A practical finished configuration is therefore:

services:

  cloudbeaver:
    image: dbeaver/cloudbeaver:latest
    container_name: cloudbeaver

    restart: unless-stopped

    ports:
      - "127.0.0.1:8978:8978"

    volumes:
      - ./workspace:/opt/cloudbeaver/workspace

    extra_hosts:
      - "host.docker.internal:host-gateway"

    environment:
      JAVA_OPTS: "-Xms512m -Xmx2048m"

Save it as:

/opt/cloudbeaver/docker-compose.yml

Start:

cd /opt/cloudbeaver
docker compose pull
docker compose up -d

Final Nginx configuration

Before Certbot modifies it, the virtual host should look similar to:

server {
    listen 80;
    listen [::]:80;

    server_name db.example.com;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:8978;

        proxy_http_version 1.1;

        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_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_read_timeout 3600;
        proxy_send_timeout 3600;
    }
}

Then:

nginx -t
systemctl reload nginx

followed by:

certbot --nginx -d db.example.com

Final verification checklist

Run:

docker ps

CloudBeaver should show:

Up

Check localhost:

curl -I http://127.0.0.1:8978

Check Nginx:

nginx -t

Check HTTPS:

curl -I https://db.example.com

Check listening ports:

ss -lntp

You should have public listeners for:

:22
:80
:443

but CloudBeaver should appear only on:

127.0.0.1:8978

Finally test certificate renewal:

certbot renew --dry-run

At that point the deployment path is:

                      HTTPS
                        |
                        v
              +-------------------+
              |       Nginx       |
Internet ---> |      :443         |
              +-------------------+
                        |
                 127.0.0.1:8978
                        |
                        v
              +-------------------+
              |    CloudBeaver    |
              |      Docker       |
              +-------------------+
                 |       |       |
                 v       v       v
              MySQL   PostgreSQL SQL Server
                 \       |       /
                  \ Private/VPN /
                   \   Network  /

This gives you a persistent, TLS-secured CloudBeaver Community deployment on Ubuntu without exposing CloudBeaver’s native port to the public Internet. The official CloudBeaver documentation recommends Docker as the easiest deployment mechanism, uses port 8978 as the default application endpoint, and documents Nginx as the appropriate manual proxy approach for Community Edition.

Conclusion

You now know how to deploy CloudBeaver on Ubuntu VPS!

References

Official documentation used for the current deployment details:

Add as Preferred Source on Google

What is CloudBeaver?

CloudBeaver VPS requirements

Compare Ubuntu VPS Plans

How to Deploy CloudBeaver on Ubuntu VPS

Connect to the Ubuntu VPS

Update Ubuntu

Configure the Server Hostname

Configure DNS

Install Docker Engine

Enable Docker

Create the CloudBeaver directory structure

restart: unless-stopped

127.0.0.1:8978:8978

Workspace volume

Optional: Pin CloudBeaver to a specific version

Start CloudBeaver

Check the CloudBeaver logs

Test CloudBeaver locally

Install Nginx

Create the CloudBeaver Nginx virtual host

Test the Nginx configuration

Configure the Ubuntu firewall

Important Docker firewall note

Test CloudBeaver through Nginx

Install Certbot

Obtain a Let’s Encrypt certificate

Test HTTPS

Verify certificate renewal

Complete the CloudBeaver initial setup wizard

Log into CloudBeaver

Add a PostgreSQL database connection

Connecting to MariaDB or MySQL

Do not expose database ports unnecessarily

Allow CloudBeaver through the database firewall

Connecting to a database running on the same VPS

Verify CloudBeaver container networking

Adjust CloudBeaver Java memory

Check CloudBeaver resource usage

View CloudBeaver logs

View Nginx logs

Restart CloudBeaver

Stop CloudBeaver

Back up CloudBeaver

Upgrade CloudBeaver

Remove old Docker images

Production security recommendations

Require HTTPS

Keep port 8978 private

Restrict database privileges

Use private networking

Disable unnecessary anonymous functionality

Keep CloudBeaver updated

Keep Ubuntu updated

Back up the workspace

Optional: restrict CloudBeaver to specific source IPs

Optional: protect CloudBeaver with HTTP Basic Authentication

Troubleshooting: CloudBeaver container won’t start

Troubleshooting: 502 Bad Gateway

Troubleshooting: database connection timeout

Troubleshooting: connection refused

Troubleshooting: CloudBeaver cannot access localhost database

Troubleshooting: CloudBeaver works by IP but not domain

Troubleshooting WebSockets

Final Docker Compose file

Final Nginx configuration

Final verification checklist

Conclusion

References

Related Posts

Editorial Staff

Leave a Reply Cancel reply

Services

Categories

Recent Posts

Save on VPS Hosting!

We’re Social!

Rad Web Hosting Blog

`restart: unless-stopped`

`127.0.0.1:8978:8978`