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=trueturns onDELETE /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=debuglogs every request. Read them withdocker logs -f tamarackdb.--rmdeletes the data when the container stops. Mount a volume on/datato keep it (see Docker).
Binaries
Each release publishes four binaries for Linux, on amd64 and arm64:
| Binary | What it does |
|---|---|
tamarackdb-server | The HTTP server |
tamarackdb-init | Creates a new database, empty or from a dump of events. The server needs one to start |
tamarackdb-backup | Copies new events from an instance into a backup file |
tamarackdb-migrate | Brings 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 -cchecks the zip against the release’sSHA256SUMS. It fails, and printsFAILED, when they don’t match: don’t install that zip.- The binaries are static: no runtime and no library to install.
--versionprints a binary’s version and exits.- To build them from source instead, run
make buildin a clone of the repository, with Go. The binaries land inbin/. Details are in CONTRIBUTING.md.
Production
Check each point before an instance holds real data:
- Run the server as its own system user, never as root.
- Keep
dataDirreadable by that user only (0700). - Run the server on the application’s host, on its unix socket (see Security).
- From another host, go through a reverse proxy for TLS, and set
authTokenFile(see Security). - Make the token file readable by the server’s user only (
chmod 600). - Leave
devModeoff. - Size
maxQueuedWrites(see Configuration). - Watch
/healthand/stats(see Monitoring). - Schedule
tamarackdb-backup(see Backup and Import), and the dailyPOST /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.targetsystemd 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/tokencan then be owned by root, withchmod 600.- systemd copies it into a directory only the service can read, and
%dnames 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 tamarackdbOn 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/runis emptied at every reboot. For a lasting service, use the systemd unit.tamarackdb-initcreatesdataDirand 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:latestThe 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_FILEorTAMARACKDB_ALLOW_NO_AUTH=true. It can’t see whether its port is private.Without a token, publish the port on
127.0.0.1only. A plain-p 8085:8085opens 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 UID10001: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:latestThe 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
/dataholds no database, the image creates one and logstamarackdb-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-tokenwith its permissions on the host: it must be readable by UID10001. - The application gets the token by its own means, a secret of its own for example.