Skip to content

Install

Getting an instance running: on your own machine, from the release binaries, in production with systemd, or in Docker.

Local development

docker run -d --rm --name tamarackdb -p 127.0.0.1:8085:8085 \
  -e TAMARACKDB_DEV_MODE=true \
  -e TAMARACKDB_LOG_LEVEL=debug \
  ghcr.io/tamarackdb/tamarackdb:latest
  • The API is at http://127.0.0.1:8085, reachable from your machine only.
  • TAMARACKDB_DEV_MODE=true turns on DELETE /events, to start each test run from an empty store (see Development mode). It also lets the server run without a token.
  • TAMARACKDB_LOG_LEVEL=debug logs every request. Read them with docker logs -f tamarackdb.
  • --rm deletes the data when the container stops. Mount a volume on /data to keep it (see Docker).

Binaries

Each release publishes four binaries for Linux, on amd64 and arm64:

BinaryWhat it does
tamarackdb-serverThe HTTP server
tamarackdb-initCreates a new database, empty or from a dump of events. The server needs one to start
tamarackdb-backupCopies new events from an instance into a backup file
tamarackdb-migrateBrings a database to a new major version (see Upgrade)

Download a release and install its binaries (see the releases for the latest version):

VERSION=v1.0.0 ARCH=amd64
curl -fLO https://github.com/tamarackdb/tamarackdb/releases/download/$VERSION/tamarackdb-$VERSION-linux-$ARCH.zip
curl -fLO https://github.com/tamarackdb/tamarackdb/releases/download/$VERSION/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missing
unzip tamarackdb-$VERSION-linux-$ARCH.zip
sudo install -m 755 tamarackdb-$VERSION-linux-$ARCH/tamarackdb-* /usr/local/bin/
  • sha256sum -c checks the zip against the release’s SHA256SUMS. It fails, and prints FAILED, when they don’t match: don’t install that zip.
  • The binaries are static: no runtime and no library to install.
  • --version prints a binary’s version and exits.
  • To build them from source instead, run make build in a clone of the repository, with Go. The binaries land in bin/. Details are in CONTRIBUTING.md.

Production

Check each point before an instance holds real data:

  1. Run the server as its own system user, never as root.
  2. Keep dataDir readable by that user only (0700).
  3. Run the server on the application’s host, on its unix socket (see Security).
  4. From another host, go through a reverse proxy for TLS, and set authTokenFile (see Security).
  5. Make the token file readable by the server’s user only (chmod 600).
  6. Leave devMode off.
  7. Size maxQueuedWrites (see Configuration).
  8. Watch /health and /stats (see Monitoring).
  9. Schedule tamarackdb-backup (see Backup and Import), and the daily POST /optimize (see Maintenance).

systemd

A unit for the server, running as user tamarackdb:

# /etc/systemd/system/tamarackdb.service
[Unit]
Description=TamarackDB
After=network.target

[Service]
User=tamarackdb
Group=tamarackdb
ExecStart=/usr/local/bin/tamarackdb-server --config /etc/tamarackdb/config.toml
Restart=on-failure
RuntimeDirectory=tamarackdb
RuntimeDirectoryMode=0755
StateDirectory=tamarackdb
StateDirectoryMode=0700
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
PrivateDevices=true
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

systemd creates /run/tamarackdb for the socket, and /var/lib/tamarackdb for the data, both owned by tamarackdb. With this config.toml:

[server]
socketMode = "0660"
dataDir = "/var/lib/tamarackdb"

To turn authentication on, let systemd hand the token file to the server. Add to [Service]:

LoadCredential=token:/etc/tamarackdb/token
Environment=TAMARACKDB_AUTH_TOKEN_FILE=%d/token
  • /etc/tamarackdb/token can then be owned by root, with chmod 600.
  • systemd copies it into a directory only the service can read, and %d names that directory.

Create the user and the database, then start the service:

sudo useradd --system --user-group --no-create-home --shell /usr/sbin/nologin tamarackdb
sudo install -d -o tamarackdb -g tamarackdb -m 700 /var/lib/tamarackdb
sudo -u tamarackdb /usr/local/bin/tamarackdb-init --data-dir /var/lib/tamarackdb
sudo systemctl enable --now tamarackdb

On systemctl stop, the server lets a write already running finish, and turns away the requests still waiting with 503 ShuttingDown.

Running the binaries

Run every command that touches dataDir as the server’s user: the server, tamarackdb-init, and any sqlite3 you run by hand. A file created by another user, such as root, is one the server can’t open, and it refuses to start.

sudo install -d -o tamarackdb -g tamarackdb -m 755 /run/tamarackdb
sudo -u tamarackdb /usr/local/bin/tamarackdb-init --data-dir /path/to/data
sudo -u tamarackdb /usr/local/bin/tamarackdb-server --config /path/to/config.toml
  • /run is emptied at every reboot. For a lasting service, use the systemd unit.
  • tamarackdb-init creates dataDir and a new database. It never overwrites an existing database.
  • The server never creates a database: it refuses to start when the file is missing.
  • The server refuses to start when the database’s schema version doesn’t match its own. It never changes the schema.
  • At startup, the server prints its resolved configuration to stdout (never the token).

Docker

Each release publishes an image for linux/amd64 and linux/arm64. Pin a version with ghcr.io/tamarackdb/tamarackdb:v<version> (see the releases).

docker run -d -p 127.0.0.1:8085:8085 -v tamarackdb-data:/data \
  -e TAMARACKDB_ALLOW_NO_AUTH=true \
  ghcr.io/tamarackdb/tamarackdb:latest
  • The image is set up with TAMARACKDB_* environment variables only (see Configuration).

  • It listens over TCP on port 8085, and keeps the database in /data.

  • The server refuses to start until it’s given TAMARACKDB_AUTH_TOKEN_FILE or TAMARACKDB_ALLOW_NO_AUTH=true. It can’t see whether its port is private.

  • Without a token, publish the port on 127.0.0.1 only. A plain -p 8085:8085 opens the API to anyone who can reach the host. To expose it, set a token and put a reverse proxy in front for TLS (see Security).

  • To set a token, mount its file read-only and name it in TAMARACKDB_AUTH_TOKEN_FILE. The file must be readable by UID 10001:

    sudo chown 10001 /etc/tamarackdb/token
    docker run -d -p 127.0.0.1:8085:8085 -v tamarackdb-data:/data \
      -v /etc/tamarackdb/token:/run/secrets/tamarackdb-token:ro \
      -e TAMARACKDB_AUTH_TOKEN_FILE=/run/secrets/tamarackdb-token \
      ghcr.io/tamarackdb/tamarackdb:latest
  • The server runs as UID and GID 10001. To mount a host directory instead of a named volume, give it to that user first: sudo install -d -o 10001 -g 10001 -m 700 /srv/tamarackdb.

  • When /data holds no database, the image creates one and logs tamarackdb-init: created /data/tamarackdb.sqlite. If that line shows up on a restart, the container got an empty volume: check its name and mount point.

Alongside the application

When the application runs in a container too, put both on the same Docker network and publish no port. The application reaches TamarackDB by its service name:

services:
  tamarackdb:
    image: ghcr.io/tamarackdb/tamarackdb:latest
    environment:
      TAMARACKDB_ALLOW_NO_AUTH: "true"
    volumes:
      - tamarackdb-data:/data
  app:
    image: my-app
    environment:
      TAMARACKDB_URL: http://tamarackdb:8085

volumes:
  tamarackdb-data:

Every container on that network can reach the API. If some of them aren’t trusted, give the server a token instead of TAMARACKDB_ALLOW_NO_AUTH, as a Compose secret:

services:
  tamarackdb:
    image: ghcr.io/tamarackdb/tamarackdb:latest
    environment:
      TAMARACKDB_AUTH_TOKEN_FILE: /run/secrets/tamarackdb-token
    secrets:
      - tamarackdb-token
    volumes:
      - tamarackdb-data:/data

secrets:
  tamarackdb-token:
    file: ./tamarackdb-token

volumes:
  tamarackdb-data:
  • Compose mounts ./tamarackdb-token with its permissions on the host: it must be readable by UID 10001.
  • The application gets the token by its own means, a secret of its own for example.