Pilotbase Add Connection form with a Docker service name as the host

Self-hosted deployment panels have become very good at running databases. In Coolify, Dokploy, Easypanel, Openship or Doktainer you click PostgreSQL or MySQL, and a minute later your app has a database on a private Docker network. Then you need to look inside it, and there is no obvious way in.

The request keeps coming up. On Openship, issue #968 asks for "integrated database management tools such as phpMyAdmin, pgAdmin, or DbGate directly to the database service, similar to Easypanel". The same request is open on Doktainer as #8. Until a panel builds it in, you can add a database GUI yourself. This guide does it with Pilotbase, an open-source (MIT) client for PostgreSQL, MySQL, MongoDB, Redis and 15 other engines, but most of it applies whichever web client you pick.

The one rule: don't publish the database port

The quick fix is to expose 5432 or 3306 on the server and connect a desktop client to it. Don't. A database port open to the internet gets password-guessing traffic within hours, and the panels keep databases on an internal network for a good reason. The better shape is the opposite one: put the GUI inside the same private network as the databases, and put the GUI, not the database, behind your panel's HTTPS proxy and a login.

That gives you three pieces: the GUI container joined to the panel's network, a read-only database user for day-to-day browsing, and authentication in front of the GUI's URL.

1. Find the network and the internal host name

Every panel gives each database an internal address that other containers on the same network can reach. Where to find it:

Easypanel: the database service's Credentials tab shows the internal host and an internal connection URL; services in the same project use it. Coolify: resources can join the shared coolify network ("Connect to Predefined Network" on a Compose stack), and a database in another stack is reached by its full container name, such as postgres-<uuid>. Dokploy: services share the external dokploy-network. Openship, Doktainer and anything else Docker-based: ask Docker directly.

bash
docker ps --format '{{.Names}}\t{{.Image}}' | grep -Ei 'postgres|mysql|mariadb|mongo|redis'
docker inspect -f '{{range $k, $v := .NetworkSettings.Networks}}{{$k}} {{end}}' <db-container>

The second command prints the networks the database container is on. Note the network name and the container (or service) name: that name is the host you'll type into the GUI, and the port is the database's internal port (5432, 3306), not a published one.

2. Run Pilotbase on that network

Pilotbase publishes a multi-arch image (amd64 and arm64) on the GitHub Container Registry. It keeps its own small Postgres for saved connections and query history, so the stack has two services. Add it to your panel as a Docker Compose app:

The public ghcr.io/icedsg/pilotbase package page with tagged versions 3.0.0-beta10 and edge
The public image on ghcr.io. Pin a version tag rather than edge.
yaml
services:
  pilotbase:
    image: ghcr.io/icedsg/pilotbase:3.0.0-beta10
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql+psycopg2://pilotbase:${PB_DB_PASSWORD}@pilotbase-db:5432/pilotbase
      SECRET_KEY: ${PB_SECRET_KEY}
      ENCRYPTION_KEY: ${PB_ENCRYPTION_KEY}
      ENVIRONMENT: production
      CORS_ORIGINS: https://db.example.com
    volumes:
      - pilotbase_backups:/app/api/backups
    depends_on:
      pilotbase-db:
        condition: service_healthy
    networks: [default, panel]
    # no "ports:" here: the panel's proxy routes db.example.com to port 8000

  pilotbase-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_DB: pilotbase
      POSTGRES_USER: pilotbase
      POSTGRES_PASSWORD: ${PB_DB_PASSWORD}
    volumes:
      - pilotbase_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pilotbase"]
      interval: 10s
      retries: 5

volumes:
  pilotbase_pgdata:
  pilotbase_backups:

networks:
  panel:
    external: true
    name: dokploy-network   # or coolify, or whatever network your databases are on

Set the three variables in the panel's environment section. Generate them once and keep them. ENCRYPTION_KEY encrypts every saved connection password, so if it changes later Pilotbase can no longer read them and you'll have to re-enter each one.

bash
openssl rand -hex 32                     # PB_SECRET_KEY
openssl rand -hex 24                     # PB_DB_PASSWORD
python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"   # PB_ENCRYPTION_KEY

Then attach a domain such as db.example.com to the pilotbase service on port 8000 in the panel's UI. The panel's proxy (Traefik or Caddy, depending on the panel) issues the certificate. Nothing is published on the host.

3. Put a login in front of it

This step isn't optional. Self-hosted Pilotbase runs in single-user mode by default: there is no login screen, and each browser gets its own workspace via a cookie. A stranger who finds the URL can't see your saved connections, but they get a database client sitting inside your private network, and they can try to log in to anything on it.

So protect the domain at the proxy. Easypanel has HTTP basic auth on each service and Dokploy on each application. For Compose stacks and on Coolify, Traefik's basic-auth middleware works through labels. A VPN such as Tailscale or WireGuard, or an access proxy that asks for a login before forwarding, is better still. Whichever you use, check from a private browser window that the URL asks for credentials before Pilotbase loads.

4. Connect with a read-only user

Most of the time you are looking, not changing. Create a user that can only read, and save that as the everyday connection. On PostgreSQL 14 and later one built-in role does it:

sql
-- PostgreSQL 14+
CREATE ROLE pilotbase_ro LOGIN PASSWORD 'a-long-random-password';
GRANT pg_read_all_data TO pilotbase_ro;

-- MySQL / MariaDB
CREATE USER 'pilotbase_ro'@'%' IDENTIFIED BY 'a-long-random-password';
GRANT SELECT, SHOW VIEW ON shop.* TO 'pilotbase_ro'@'%';

We tried the Postgres one: SELECT count(*) FROM orders works, and an UPDATE fails with permission denied for table orders. Keep the owner account for the rare write, saved as a separate connection with an obvious name.

In Pilotbase, click + in the Connections panel. The host is the internal name from step 1, the port is the internal port, and Test Connection lists the databases it can see.

Pilotbase Add Connection form: name Shop app DB (panel), PostgreSQL, host shop-db, port 5432, database shop, username pilotbase_ro
The host is the Docker service name, not localhost and not the server's public IP.

If the test times out, the two containers are not on a shared network: re-check the network name in the Compose file. If it is refused, the host or port is wrong; use the container's internal port, not a host mapping.

What you get

Once it is connected, you browse schemas and tables, run queries with results you can export to CSV, and keep the history of what you ran. One client covers the engines a panel typically offers (PostgreSQL, MySQL, MariaDB, MongoDB, Redis) instead of a phpMyAdmin for one and a pgAdmin for another.

Pilotbase showing the orders table of a PostgreSQL database, with the connection tree on the left and 50 rows in the results grid
Right-click a table to view its rows, show its columns or export it as SQL.

Running inside the server also makes two things practical that a laptop client can't do as well. Backups run next to the database and are written to the pilotbase_backups volume (more in Migrate, back up, and expose your data safely). And on the Docker build you can turn tables into a REST API for an internal tool without writing a backend.

If you'd rather use something else

It's a fair choice. Adminer is one PHP file and covers MySQL, PostgreSQL, SQLite and more. DbGate is a capable multi-engine client (GPL-3.0) and is what Easypanel builds in. pgAdmin and phpMyAdmin are the deepest tools for their one engine each. The pattern above (same private network, no published database port, login at the proxy, read-only user) is what keeps any of them safe. Pilotbase's case is one MIT-licensed client for every engine on the server, with an optional AI agent that writes queries and waits for your approval before any write.

Run Pilotbase next to your databases: one image, every engine your panel runs, MIT-licensed.

Get Pilotbase

Sources: Openship issue #968, Doktainer issue #8, Easypanel docs, Coolify: service networking, Dokploy: Docker Compose, PostgreSQL predefined roles, Pilotbase installation guide.