Self-contained install (bundled database)

This install runs Tagaris and its PostgreSQL database in one container. There is no separate database to install or connect: the container runs PostgreSQL itself and keeps everything in one place. It uses the goodhallsolutions/tagaris-bundled image.

Tagaris installs three ways, and this is the self-contained one. It suits a single machine, and platforms that run one container per app and have no Docker Compose, such as Unraid's Community Applications, single-container Portainer or CasaOS. The alternatives are the standard install, which keeps the database in its own container, and a dedicated-database install, which points Tagaris at a PostgreSQL server you already run.

Requirements

• A host that runs a Docker container, with about 1 GB of memory and a little disk. More assets and photos need more disk.
• Nothing else. The database is inside the image.

Install with Docker Compose

1. Create a directory

mkdir -p /opt/tagaris && cd /opt/tagaris

2. Create docker-compose.yml

Save the following as docker-compose.yml. One service and two volumes; the secret and the URL come from the .env file next to it.

services:
  app:
    image: goodhallsolutions/tagaris-bundled:latest
    restart: unless-stopped
    environment:
      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
      BETTER_AUTH_URL: ${BETTER_AUTH_URL}
      BETTER_AUTH_TRUSTED_ORIGINS: ${BETTER_AUTH_TRUSTED_ORIGINS:-}
      API_ENABLED: ${API_ENABLED:-true}
      TZ: ${TZ:-Europe/London}
      SSO_ISSUER: ${SSO_ISSUER:-}
      SSO_CLIENT_ID: ${SSO_CLIENT_ID:-}
      SSO_CLIENT_SECRET: ${SSO_CLIENT_SECRET:-}
      SSO_PROVIDER_NAME: ${SSO_PROVIDER_NAME:-}
    ports:
      - "3000:3000"
    volumes:
      - data:/app/data
      - uploads:/app/uploads
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3000/api/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 40s

volumes:
  data:
  uploads:

The examples use the latest tag for simplicity. For anything beyond a trial, pin to a major version such as goodhallsolutions/tagaris-bundled:2 so upgrades stay within version 2. See Upgrading for tags, update steps and database upgrades.

3. Create .env

Save this as .env in the same directory, then change the secret and the URL.

# BETTER_AUTH_URL is the public address people reach the app on, not localhost.
# Generate the secret with: openssl rand -base64 32
BETTER_AUTH_SECRET=change_me_generate_with_openssl_rand_base64_32
BETTER_AUTH_URL=https://assets.example.com
BETTER_AUTH_TRUSTED_ORIGINS=

# Timezone for scheduled jobs (daily digest, backups, syncs).
TZ=Europe/London

# Single sign-on is normally configured in the app; leave these blank.
SSO_ISSUER=
SSO_CLIENT_ID=
SSO_CLIENT_SECRET=
SSO_PROVIDER_NAME=

4. Start it

docker compose up -d

On the first start the container sets up its database, applies migrations, then listens on port 3000. Allow a minute or two for the first image pull.

5. Sign in

Open http://your-host:3000. The first visit opens the setup wizard, which creates your organisation and the first administrator account. That account is the install owner and the break-glass login, so give it a strong password and store it safely.

6. Put it behind HTTPS

For anything beyond a first look on a private network, serve Tagaris through a reverse proxy that terminates TLS (Cloudflare, nginx or Caddy), and set BETTER_AUTH_URL to the https:// address. Session cookies and sign-in depend on it.

On Unraid

Add the Tagaris template from Community Applications. It installs this image and asks for the same two values, the auth secret and the public URL, on the form. The database and photos persist under /mnt/user/appdata/tagaris by default.

Install without Compose (plain docker run)

docker run -d --name tagaris \
  -e BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  -e BETTER_AUTH_URL="http://your-host:3000" \
  -v /opt/tagaris/data:/app/data \
  -v /opt/tagaris/uploads:/app/uploads \
  -p 3000:3000 \
  goodhallsolutions/tagaris-bundled:latest

Migrations run automatically at start, and the first visit opens the setup wizard.

Configuration

All settings are environment variables, read when the container starts: change a value, then recreate the container to apply it. There are no database settings, because the database is internal.

Variable	Purpose
BETTER_AUTH_SECRET	Signs session cookies and encrypts stored secrets. Set a strong random value, keep it out of version control, and store a copy safely.
BETTER_AUTH_URL	The public URL the app is served from, for example https://assets.example.com. Used for auth callbacks, invite links, SSO and the QR label codes. Set it to the address people actually use, not localhost.
BETTER_AUTH_TRUSTED_ORIGINS	Optional extra origins allowed to make auth requests, comma-separated. Useful for reaching a test instance by IP. Leave blank in production.
TZ	Timezone for scheduled jobs, such as the daily digest and backups. Defaults to Europe/London.
API_ENABLED	Whether the REST API at /api/v1 is available. Default true. Set to false to turn it off install-wide.
SSO_ISSUER, SSO_CLIENT_ID, SSO_CLIENT_SECRET, SSO_PROVIDER_NAME	Normally blank: single sign-on is configured in the app.

Applying a purchased licence key needs no environment change: enter it in Application settings. See Licensing.

Persistent storage

The container is disposable. Everything that must survive a rebuild lives in two volumes:

• data (mounted at /app/data): the PostgreSQL database and uploaded asset photos, thumbnails and attachments. This is the register itself.
• uploads (mounted at /app/uploads): other uploaded files, including the backups folder written by the in-app scheduled backups.

Back up both. Rebuilding or updating the image never touches the volumes.

To keep the data at a path you control, on a NAS or Unraid box, or so host-level backup tooling can see the files, replace the volume names with host paths:

  app:
    volumes:
      - /srv/tagaris/data:/app/data
      - /srv/tagaris/uploads:/app/uploads

The in-app scheduled backups (Application settings) work the same as on any other install and are the easiest way to keep a portable copy. See Backups and restore.

Troubleshooting

• QR labels or invite links point at localhost, or sign-in fails behind a proxy: BETTER_AUTH_URL must match the address in the browser's URL bar. Change it, then recreate the container.
• Scheduled jobs run at the wrong time: set TZ to your timezone.
• A changed setting has no effect: environment variables are read when the container starts, so recreate the container to apply changes.
• The container will not start after an image update, with a message about PostgreSQL versions: this is a PostgreSQL major upgrade. See Upgrading.