Get started with Quellery

All you need is Docker. Quellery runs as a single container with built-in persistence.

Download the compose file

Save this docker-compose.yml to an empty directory, or download it directly.

services:
  quellery:
    image: lancewalton/quellery:latest
    ports:
      - "8080:8080"
    volumes:
      - quellery-data:/data
    environment:
      - ENCRYPTION_KEY=change-me-to-a-secure-key
      - SESSION_SECRET=change-me-to-a-session-secret

volumes:
  quellery-data:

Replace ENCRYPTION_KEY and SESSION_SECRET with your own random strings. These encrypt stored database credentials and sign session tokens respectively.

Download docker-compose.yml

Start Quellery

docker compose up -d

Then open http://localhost:8080 in your browser.

Create your account

On first launch you'll be prompted to create an admin account. Once logged in, create a database connection, select a schema, and you'll see all of your tables.

Alternative: Run without Docker

If you prefer not to use Docker, you can download the fat JAR and run Quellery directly with Java.

Prerequisites

Java 21 or later. Check with java -version.

Download

Download the latest release:

Download quellery.jar 0.0.6

Run

REPOSITORY_DIR=./data \
ENCRYPTION_KEY=change-me-to-a-secure-key \
SESSION_SECRET=change-me-to-a-session-secret \
java -jar quellery.jar

Then open http://localhost:8080 in your browser.

REPOSITORY_DIR is the directory where Quellery stores its SQLite database, event snapshots, and licence file. It will be created if it doesn't exist.

Connecting to databases

When you create a database connection, Quellery asks for the database type, hostname, port, database name, and credentials. It supports PostgreSQL, MySQL, and H2.

Database on the same machine

If your database runs on the same machine as Docker, use host.docker.internal as the hostname. This is Docker's special name for reaching the host machine from inside a container.

Database on a remote machine

Use the IP address or hostname of the remote machine directly.

Database in another container

Put the database container on the same Docker network as Quellery, then use the container name as the hostname.

Configuration

VariableRequiredDefaultDescription
ENCRYPTION_KEYYes—Encrypts stored database credentials
SESSION_SECRETYes—Signs session tokens
SESSION_EXPIRY_HOURSNo24Login session duration (hours)
LICENCE_FILENo/data/licence.jsonPath to licence file inside the container
PROMOTE_ADMIN_EMAILNo—Promote an existing user to admin on startup

Data storage

All Quellery data — the SQLite database, event snapshots, and licence file — is stored in /data inside the container. The compose file mounts this as a named volume so your data persists across restarts.

Emergency admin recovery

If all admin accounts are locked out, set PROMOTE_ADMIN_EMAIL to an existing user's email. On the next startup that user will be promoted to administrator. Remove the variable afterwards.

Updating

Pull the latest image and restart:

docker compose pull
docker compose up -d

Your data is preserved in the quellery-data volume.