Create your administrator account
On first launch you'll see a welcome screen. Enter a display name, email address, and password (minimum 8 characters). This becomes the first administrator account — more users can be added later.
All you need is Docker. Quellery runs as a single container using either SQLite (zero-config, file-based) or PostgreSQL (shared-server deployments) for its own persistence. The example below uses SQLite — see Configuration to switch to PostgreSQL.
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:
- DATABASE_URL=jdbc:sqlite:/data/quellery.sqlite
- 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.
If you prefer not to use Docker, you can download the fat JAR and run Quellery directly with Java. Like Docker, you can use either SQLite or PostgreSQL — the example below uses SQLite.
Java 21 or later. Check with java -version.
DATABASE_URL=jdbc:sqlite:./data/quellery.sqlite \
ENCRYPTION_KEY=change-me-to-a-secure-key \
SESSION_SECRET=change-me-to-a-session-secret \
java -jar quellery.jarThen open http://localhost:8080 in your browser.
DATABASE_URL is the JDBC URL for Quellery's own database. Use jdbc:sqlite:<path> for SQLite or jdbc:postgresql://host:port/dbname for PostgreSQL.
| Variable | Required | Default | Description |
|---|---|---|---|
DATABASE_URL | Yes | — | JDBC URL for Quellery's database (jdbc:sqlite:... or jdbc:postgresql://...) |
DATABASE_USERNAME | No | — | Database username (PostgreSQL only) |
DATABASE_PASSWORD | No | — | Database password (PostgreSQL only) |
ENCRYPTION_KEY | Yes | — | Encrypts stored database credentials |
SESSION_SECRET | Yes | — | Signs session tokens |
SESSION_EXPIRY_HOURS | No | 24 | Login session duration (hours) |
PROMOTE_ADMIN_EMAIL | No | — | Promote an existing user to admin on startup |
By default Quellery uses SQLite, storing its database at the path specified in DATABASE_URL. The Docker compose file mounts /data as a named volume so your data persists across restarts. Alternatively, set DATABASE_URL to a PostgreSQL JDBC URL with DATABASE_USERNAME and DATABASE_PASSWORD for shared-server deployments.
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.
Pull the latest image and restart:
docker compose pull
docker compose up -dYour data is preserved in the quellery-data volume.
Now that Quellery is running, open http://localhost:8080 in your browser.
On first launch you'll see a welcome screen. Enter a display name, email address, and password (minimum 8 characters). This becomes the first administrator account — more users can be added later.
After logging in you see the main dashboard. Use the dropdowns along the top to select a database, schema, and model. The left panel lists tables, types, and queries for the selected schema.
Go to Admin in the navigation bar to create your first connection. Give it a name, choose the database type (PostgreSQL, MySQL, or H2), and enter the credentials. You can also configure the connection pool size and a refresh interval.
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.
Use the IP address or hostname of the remote machine directly.
Put the database container on the same Docker network as Quellery, then use the container name as the hostname.