Deploying quanthea
quanthea ships as one Docker image, ghcr.io/jboix/quanthea, for linux/amd64 and linux/arm64. It
keeps its state in two volumes and reads an optional configuration file.
Quick start
docker run -d --name quanthea -p 3000:3000 \
-v quanthea-data:/data \
-v quanthea-keys:/keys \
ghcr.io/jboix/quanthea
The first start creates the user admin and writes its password to the log, once:
docker logs quanthea 2>&1 | grep password
Sign in at http://localhost:3000 as admin with that password. quanthea then asks for your own
email and password; nothing else opens until you set them.
With a configuration file
Declare the first admin, and later the model, sources and sign-in, in a quanthea.yaml:
server:
publicUrl: http://localhost:3000
users:
admin:
password: ${ADMIN_PASSWORD}
Put the secrets it refers to in a .env file next to it:
ADMIN_PASSWORD=choose-a-long-password
Then start quanthea with the file mounted:
docker run -d --name quanthea -p 3000:3000 \
-v quanthea-data:/data \
-v quanthea-keys:/keys \
-v ./quanthea.yaml:/etc/quanthea/quanthea.yaml:ro \
--env-file .env \
ghcr.io/jboix/quanthea
Sign in at http://localhost:3000 as admin, with the ADMIN_PASSWORD of .env. The
configuration file lists everything it can declare.
Pin and verify the image
ghcr.io/jboix/quanthea with no tag is :latest, which moves with every release. Pin a release
tag such as ghcr.io/jboix/quanthea:v0.3.0 to choose when you upgrade. The Compose file in
deploy/ names the latest release’s tag, and each release updates it.
Every release after v0.3.0 is signed with cosign by the
Release workflow on main, without a key, and carries its SBOM and build provenance. Releases up
to v0.3.0 are not signed. Check the signature before you run a new tag, with your version in place
of vX.Y.Z:
cosign verify ghcr.io/jboix/quanthea:vX.Y.Z \
--certificate-identity https://github.com/jboix/quanthea/.github/workflows/release.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
It prints the signature it verified, with the image’s digest. A signature from another workflow, another branch or another repository fails the check. Sigstore’s public log records every signature: search the digest at https://search.sigstore.dev.
To pin the exact image, use that digest: ghcr.io/jboix/quanthea@sha256:….
The SBOM lists the packages inside the image, and the provenance says which commit and workflow built it. Read them with Docker:
docker buildx imagetools inspect ghcr.io/jboix/quanthea:vX.Y.Z --format '{{ json .SBOM }}'
docker buildx imagetools inspect ghcr.io/jboix/quanthea:vX.Y.Z --format '{{ json .Provenance }}'
Try main before a release
Every night main is built into ghcr.io/jboix/quanthea:nightly, when it changed and its checks
passed. Each build also keeps its own tag, :main-<short commit>, such as :main-61f1824. A
maintainer can build one at any time from the Nightly workflow on GitHub.
Run a nightly on a test instance, or on a copy of your data, never on the instance people use. A
nightly may migrate the database, and an older release does not start on a database a newer
version migrated: there is no way back but a backup. A migration never changes once it is on
main, so the next release upgrades a nightly’s database as it would any other.
docker pull ghcr.io/jboix/quanthea:nightly
Check its signature as for a release, with the Nightly workflow in the identity:
cosign verify ghcr.io/jboix/quanthea:nightly \
--certificate-identity https://github.com/jboix/quanthea/.github/workflows/nightly.yml@refs/heads/main \
--certificate-oidc-issuer https://token.actions.githubusercontent.com
The volumes
| Path | What it holds |
|---|---|
/data | The SQLite database: dashboards, threads, users, sealed secrets |
/keys | The keys quanthea generates on first start |
The data directory must have mode 0700, readable by quanthea’s user only. The image creates
/data so. quanthea keeps the database files at mode 0600 and warns at startup when the data
directory lets its group or others in. Outside the image, create it with mkdir -m 700, or run
chmod 700 on an existing one.
/plugins holds connector plugins. It is not a volume, so a derived image can install into it;
see Connector plugins.
Back the two up apart. The database holds no secret in clear, and the keys open it: whoever holds both reads everything. Without the keys, stored credentials cannot be read.
Give your own keys instead with QUANTHEA_SECRET_KEY, QUANTHEA_SESSION_KEY and
QUANTHEA_PASSWORD_PEPPER, or their _FILE variants for Docker and Kubernetes secrets. A key you
give always wins; quanthea generates only the ones you leave out.
Configure it
quanthea reads a configuration file from /etc/quanthea, and environment variables. Both are
optional: without them, an admin sets everything up in the interface.
- The configuration file declares the server settings, users, sign-in, data sources, the model, retention, queries, charts and plugins, with secrets as references.
- Environment variables lists every variable: the public URL, the ports and directories, logging, and the three keys.
Accounts and sign-in
People always sign in. With a public URL (server.publicUrl or QUANTHEA_PUBLIC_URL), sign-in
works only from that address, and sign-in providers send people back to it; providers need it.
- Declare the first admin in
users:admin, with apasswordreference, signs in with no email; an admin keyed by email signs in with apasswordreference, or through a provider with that verified email. Then quanthea creates noadminuser of its own. - Register quanthea at each provider with the redirect URI Settings → Authentication shows.
Locked out
Inside the container, quanthea reset-admin prints a one-time link that sets the first admin’s
password; quanthea reset-admin ada@example.com names the admin. A disabled admin is enabled
again.
docker exec quanthea quanthea reset-admin
Behind a reverse proxy
People on other machines reach quanthea through a reverse proxy that serves HTTPS. Set the public
URL to its https:// address and the trusted proxy hops to the number of proxies, and let the
proxy stream answers. Behind a reverse proxy gives the details, setups for
Caddy, nginx and Traefik, and the problems people meet most.
Connector plugins
A plugin adds connector kinds: an npm package with a bundled dist/plugin.js. quanthea loads the
plugins of /plugins (QUANTHEA_PLUGINS_DIR; <data dir>/plugins outside the image) once, at
startup.
A plugin is code you install, and it runs with the server’s rights: it can read what quanthea can read, the keys and the database included. Install only plugins you trust, like any server software.
Built into a derived image (recommended)
The plugins are fixed when the image is built:
FROM ghcr.io/jboix/quanthea
RUN quanthea plugin install quanthea-plugin-sqlite@1.0.0
quanthea plugin install takes an npm name with an optional version or range, an https://
tarball URL such as a GitHub release asset, or a local .tgz or .js file. It checks npm’s
integrity hash, extracts only the manifest and the bundle, runs the static checks, and prints the
exact version installed and the pin to paste into the configuration file:
plugins:
pins:
"quanthea-plugin-sqlite": "sha256:f7eb…"
It fetches over HTTPS only, redirects included. A tarball URL has no registry hash to check, so
give it the one its publisher gives with --integrity sha512-….
Installed at runtime
docker exec quanthea quanthea plugin install quanthea-plugin-sqlite@1.0.0 installs into the
running container, and a restart loads it. This survives recreating the container only when
/plugins is mounted as its own volume; otherwise the plugin goes with the container.
Pins
A pin is a SHA-256 over the plugin’s manifest and bundle. A pinned plugin whose files do not
match is refused, and the log says to paste the pin the install printed: an upgrade changes the
pin on purpose. A plugin without a pin loads only when plugins.allowUnpinned is true
(QUANTHEA_PLUGINS_ALLOW_UNPINNED=true without a configuration file); it is false by default.
The command never writes the configuration, which is often mounted read-only.
quanthea plugin list shows each plugin and whether its pin matches; quanthea plugin remove <name> deletes one. Changes apply when quanthea restarts. A connector of a kind whose plugin is
gone stays, marked “plugin not installed”, until you reinstall the plugin or delete it.