For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/configuration.md.
Ivory

    Configuration

    How to run Ivory in production: where it keeps its data, how to upgrade it, and every environment variable it reads.

    Data and Persistence

    All Ivory data — clusters, queries, users, permissions, vaults, certificates, deployment templates — lives in /opt/ivory/data inside the container. The image declares a Docker volume for that path, so a container restart never loses it.

    To keep the data across different containers you have two options:

    • Bind mount a local directory

      docker run -p 80:80 \
  --mount type=bind,source=YOUR_LOCAL_PATH,target=/opt/ivory/data \
  --restart always veegres/ivory

    • Reuse the old container's volume

      docker run -p 80:80 --volumes-from OLD_CONTAINER_NAME --restart always veegres/ivory

    Upgrading to a New Version

    The recommended path is Backup / Restore from the Settings page. It exports your configuration — users, clusters, queries, permissions, deployment templates — into a single file that imports into a newer Ivory. The format is versioned and backward compatible, so an older backup still restores into a newer release.

    A backup says who your users are and how they sign in, and never carries a password or an outstanding registration link. After a restore, hand everybody who signs in with a password a fresh registration link from the User Manager (see Authentication).

    Mounting the data directory between containers also works, but reliably only for patch releases. For minor and major upgrades, check the supported versions page and prefer Backup / Restore.

    Environment Variables

    VariableDefaultWhat it does
    IVORY_URL_ADDRESS:80, or :443 with TLSAddress and port the server listens on
    IVORY_URL_PATH/Sub-path Ivory is served under, behind a reverse proxy. Must start with a /
    IVORY_CERT_FILE_PATH—Path to the TLS certificate inside the container
    IVORY_CERT_KEY_FILE_PATH—Path to the TLS private key inside the container
    IVORY_STATIC_FILES_PATHset by the image entrypointWhere the frontend build is served from
    IVORY_VERSION_TAGset by the buildVersion shown in the UI
    IVORY_VERSION_COMMITset by the buildCommit shown in the UI

    Running Under a Sub-path (Reverse Proxy)

    Set IVORY_URL_PATH when Ivory sits behind nginx, Traefik or any other proxy under a prefix. The path must start with a leading slash:

    docker run -p 80:80 --env IVORY_URL_PATH=/ivory --restart always veegres/ivory

    Running Under TLS / HTTPS

    Mount your certificate and key into the container — /opt/certs is the recommended location — and point both variables at them. Ivory switches its default port to 443 as soon as both are set:

    docker run -p 443:443 \
  --mount type=bind,source=YOUR_CERTS_PATH,target=/opt/certs \
  --env IVORY_CERT_FILE_PATH=/opt/certs/YOUR_CERT_NAME.crt \
  --env IVORY_CERT_KEY_FILE_PATH=/opt/certs/YOUR_KEY_NAME.key \
  --restart always veegres/ivory

    Secrets

    Every secret Ivory stores — SSH keys, database and keeper passwords, LDAP and OIDC client secrets — is encrypted with the secret word you choose during the initial setup wizard. Keep it: it is required to unlock Ivory after a restart, and it is what makes it safe to hand Ivory your credentials.