Getting started /

Quick start

Run Gresbase with Docker Compose, point it at your PostgreSQL database and open it in your browser.

On this page

Before you start#

  • Docker with Compose v2 (docker compose version should answer).
  • A PostgreSQL database the container can reach, and a user to connect with. PostgreSQL 12 or newer (see supported versions).

To look around first, start the demo with a sample database. It needs only Docker:

curl -fsSLO https://raw.githubusercontent.com/amtzespinosa/gresbase/main/deploy/docker-compose.demo.yml
docker compose -f docker-compose.demo.yml up -d

Then open http://localhost:8080. docker compose -f docker-compose.demo.yml down -v removes it.

If PostgreSQL runs on the same machine but outside Docker, localhost inside the container is not your machine. Use host.docker.internal on Docker Desktop, or the host's IP address.

Install and start#

  1. Create the Compose file#

    Save this in an empty folder as docker-compose.yml. If you don't use Compose, the docker run tab does the same in one command.

    services:
  gresbase:
    image: ghcr.io/amtzespinosa/gresbase:latest
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://USER:PASSWORD@HOST:5432/DBNAME
      GRESBASE_READ_ONLY: "false"
    volumes:
      - gresbase-data:/data
    ports:
      - "127.0.0.1:8082:8080"

volumes:
  gresbase-data:

    Gresbase listens on port 8080 inside the container. The ports line publishes it as 8082, only on your machine.

  2. Point it at your database#

    Replace USER, PASSWORD, HOST and DBNAME in DATABASE_URL. It must start with postgres:// or postgresql://. If the password contains characters such as @, : or /, percent-encode them (@ becomes %40).

    Add ?sslmode=disable at the end if your server doesn't use SSL, for example a postgres container on the same Compose network. More options in Connecting to PostgreSQL.

  3. Start it#

    Terminal
    docker compose up -d
docker compose logs -f gresbase

    The log shows starting gresbase when it's ready. If the database doesn't answer yet, Gresbase retries for up to 30 seconds and then exits with the reason. A wrong password, a missing database or an SSL error stops it at once. With restart: unless-stopped, Docker starts it again.

  4. Open Gresbase#

    Go to http://localhost:8082. The connection card at the bottom of the sidebar shows a green dot when Gresbase can reach your database. A red one comes with Can't reach the database.

Check that it's healthy#

The image has a health check that calls /healthz every 10 seconds. After the first start, docker compose ps should show the container as healthy.

docker compose ps

Who can open it#

This Compose file has no account, so there is no login. Gresbase then only answers requests addressed to localhost, 127.0.0.1 or [::1], and the sidebar shows This computer only.

To open it to other people, set an account with GRESBASE_USER and GRESBASE_PASSWORD and put HTTPS in front. See Sign-in and accounts and Security and networking.

Don't publish the port on every interface (0.0.0.0) without an account and HTTPS in front. Passwords and data would travel in clear text.

Browse without changing anything#

Set GRESBASE_READ_ONLY to "true" to explore a production database safely. Gresbase rejects every write, and its database sessions are read-only too. A Read-only badge shows in the sidebar. More in Read-only mode.

Keep the data volume#

Gresbase keeps its own data in /data: gresbase.json with settings and saved connections, secret.key that encrypts the secrets inside it, and your saved queries. Your PostgreSQL data never lives there. Details in The data volume.

Removing the volume (docker compose down -v) deletes that configuration and your saved queries, and signs everyone out.

Configuration at a glance#

Variable Default What it does
DATABASE_URL — Connection string of the database to manage. Without it, the setup wizard opens.
GRESBASE_READ_ONLY false Blocks every write to the database.
GRESBASE_USER / GRESBASE_PASSWORD — Account to sign in with. Set both or neither.
GRESBASE_SECRET_KEY Generated in /data/secret.key Encrypts the secrets in gresbase.json. At least 32 characters.

All the options are in Environment variables.

Next steps#