Beginner

10–15 min

1 GB+ RAM

Deploy WhoDB on a RamNode VPS

Lightweight, browser-based database management for PostgreSQL, MySQL, SQLite, MongoDB, Redis, and ElasticSearch — with optional AI-powered natural language queries.

What Is WhoDB?

WhoDB is a lightweight, open-source database management tool built with GoLang and React. At under 50 MB, it runs comfortably on budget VPS plans while giving you a modern, browser-based interface for PostgreSQL, MySQL, MariaDB, SQLite, MongoDB, Redis, and ElasticSearch.

Interactive schema explorer with visual relationships

Jupyter-style query scratchpad

Visual WHERE clause builder for non-SQL users

Data export and mock data generation

Optional AI-powered natural language queries

Under 50 MB footprint — runs on any VPS plan

Requirements

A RamNode VPS running Ubuntu 22.04 or 24.04 (1 GB RAM is sufficient)
Docker and Docker Compose installed (Docker installation guide)
A domain or subdomain pointed at your VPS IP
Ports 80 and 443 open in your firewall

Create a Working Directory

Create project directory

mkdir -p /opt/whodb
cd /opt/whodb

Write the Docker Compose File

/opt/whodb/docker-compose.yml

services:
  whodb:
    image: clidey/whodb:latest
    container_name: whodb
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      # Optional: AI integration via Anthropic
      # - WHODB_ANTHROPIC_API_KEY=your_key_here

      # Optional: AI integration via OpenAI
      # - WHODB_OPENAI_API_KEY=your_key_here

      # Optional: local AI via Ollama (if running on the same host)
      # - WHODB_OLLAMA_HOST=host.docker.internal
      # - WHODB_OLLAMA_PORT=11434
    volumes:
      # Uncomment if you need to connect to a local SQLite database file
      # - ./sample.db:/db/sample.db
    extra_hosts:
      - "host.docker.internal:host-gateway"

Important: The port binding uses 127.0.0.1:8080:8080 — WhoDB only listens on the loopback interface and is not directly reachable from the public internet. Never bind WhoDB directly to a public interface without authentication in front of it.

Configure nginx as a Reverse Proxy

Install nginx

apt install nginx -y

/etc/nginx/sites-available/whodb

server {
    listen 80;
    server_name db.yourdomain.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name db.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/db.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/db.yourdomain.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Optional: Restrict access to your IP only
    # allow 203.0.113.10;
    # deny all;

    # Optional: HTTP basic auth as a second layer
    # auth_basic "Restricted";
    # auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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_read_timeout 300s;
        proxy_send_timeout 300s;
    }
}

Enable the site

ln -s /etc/nginx/sites-available/whodb /etc/nginx/sites-enabled/
nginx -t

Obtain an SSL Certificate

Install Certbot and obtain SSL

apt install certbot python3-certbot-nginx -y
certbot --nginx -d db.yourdomain.com
systemctl reload nginx

Start WhoDB

Start the container

cd /opt/whodb
docker compose up -d

Verify

docker compose ps
docker compose logs -f

Navigate to https://db.yourdomain.com in your browser. You'll see the connection form.

Connect to a Database

WhoDB does not store credentials by default. Each session requires you to enter connection details. Supported databases in the Community Edition:

PostgreSQL

MySQL / MariaDB

SQLite

MongoDB

Redis

ElasticSearch

For databases in Docker containers on the same host, use the container's network alias or host.docker.internal as the hostname. For remote databases, use the server IP and ensure the port is reachable.

Enable AI-Powered Queries (Optional)

WhoDB supports natural language to SQL translation via Anthropic, OpenAI, or a local Ollama instance. Edit your docker-compose.yml and uncomment the relevant API key:

Example: enable Anthropic

    environment:
      - WHODB_ANTHROPIC_API_KEY=your_key_here

Restart the container

docker compose down && docker compose up -d

Once configured, a Chat option appears in the WhoDB sidebar for natural language queries.

Hardening Recommendations

Restrict by IP

Uncomment the allow and deny all directives in the nginx config. This is the most effective way to prevent unauthorized access.

Add HTTP basic auth

Generate password file

apt install apache2-utils -y
htpasswd -c /etc/nginx/.htpasswd youruser

Then uncomment the auth_basic lines in the nginx config and reload.

Use a non-standard subdomain

Avoid obvious names like db. or admin. if the instance is internet-facing.

Lock down the firewall

UFW basics

ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

Port 8080 does not need to be exposed — nginx handles all inbound traffic.

Connecting to Other Docker Containers

Put WhoDB and your database containers on a shared Docker network so they can reach each other by container name:

Create shared network

docker network create db_network

Updated docker-compose.yml

services:
  whodb:
    image: clidey/whodb:latest
    container_name: whodb
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    networks:
      - db_network

networks:
  db_network:
    external: true

Add db_network to your existing app's Compose file as well. Use the database container's service name as the hostname in WhoDB's connection form.

Updating WhoDB

Pull latest and restart

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

Troubleshooting

502 Bad Gateway from nginx

WhoDB isn't running or isn't listening on port 8080. Check docker compose ps and docker compose logs.

Can't connect to a database

Verify the database host is reachable from inside the container:

Test connectivity

docker exec -it whodb sh -c "nc -zv your_db_host 5432"

Connection resets after idle

Long-running queries may hit nginx's proxy timeout. The proxy_read_timeout 300s directive covers most cases — increase it for very slow queries.

WhoDB can't reach host databases

Ensure extra_hosts: host.docker.internal:host-gateway is present in the Compose file and the database is bound to 0.0.0.0 or 127.0.0.1 (not just a Unix socket).

More Deployment Guides•View Cloud VPS Plans