Install Tally

Requirements#

Use Linux on amd64 or arm64 with systemd, or macOS 13+ on Intel or Apple silicon. Native database packages must support your OS version. Use a normal user with sudo access for Linux package installation. Run Tally without sudo. PostgreSQL and ClickHouse are installed by the Tally script, so you do not need to install them separately.

macOS

Bash, curl, and tar ship with macOS. If Homebrew is not installed, run its official installer and follow its prompts, including any Command Line Tools installation:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Load Homebrew for this terminal, then install the TLS tools:

# Apple silicon uses /opt/homebrew; Intel uses /usr/local.
if [ -x /opt/homebrew/bin/brew ]; then
  eval "$(/opt/homebrew/bin/brew shellenv)"
else
  eval "$(/usr/local/bin/brew shellenv)"
fi
brew install openssl@3 python
export PATH="$(brew --prefix openssl@3)/bin:$PATH"

Also follow Homebrew's printed shell-profile instructions so it is available in future terminals. Python provides hostname validation when macOS's system LibreSSL is used.

Debian / Ubuntu

sudo apt-get update
sudo apt-get install -y \
  bash curl tar gzip openssl ca-certificates coreutils dbus-user-session

Fedora / Enterprise Linux 8+

if command -v dnf >/dev/null 2>&1; then
  sudo dnf install -y bash curl tar gzip openssl ca-certificates coreutils systemd
else
  sudo yum install -y bash curl tar gzip openssl ca-certificates coreutils systemd
fi

On Linux, sign in directly as the user who will run Tally, rather than switching users with sudo or su. Check that its user service manager is available:

systemctl --user show-environment >/dev/null && \
  echo "The systemd user service manager is ready"

If that check fails after installing the packages, log out and sign in again. Installing the systemd package does not turn a minimal container or a non-systemd host into a systemd session. Such hosts can use container or existing databases with --no-service and their own process supervisor.

Docker and Apple container are only needed if you choose those database options below.

Run the installer#

This command uses native databases and local HTTPS. To use a public hostname, prepare your certificatebefore running it. For containers or existing databases, choose a database mode first.

curl -fsSL \
  https://raw.githubusercontent.com/godellabs-ai/godel-tally/main/install.sh \
  -o install-tally.sh && \
  bash install-tally.sh --port 8443

Progress reports cover release selection, download, checksum verification, database preparation, HTTPS, and readiness. A first install can take several minutes while packages download and migrations run.

The installer creates private Tally database instances on loopback: PostgreSQL on 5433 and ClickHouse on 8124. It creates the databases and generates credentials. Existing clusters are not repurposed. Tally applies its embedded migrations on startup.

By default, PostgreSQL 18 is installed through Homebrew or PGDG; Fedora uses its distribution server package. ClickHouse comes from its Homebrew cask or official apt/RPM repository.

Choose the HTTPS port#

bash install-tally.sh --port 9443

Then open https://localhost:9443. Supported installer ports are 1024–65535. Choose a free port different from the database and internal runtime ports.

Use the same command to change an installed service. It updates the saved public URL, listening port, and upgrade origin together, then restarts Tally. The configured hostname and bind address are preserved. Reinstalling without --port retains the saved port; a new installation defaults to 8443.

HTTPS and your own SSL certificate#

For local use, the installer generates a self-signed certificate. To use your own SSL/TLS certificate, point your hostname's DNS to this server and allow the selected HTTPS port through your firewall. The certificate must cover that hostname.

Install with an existing certificate

Download the installer as shown above, replace the hostname and absolute file paths below, then run as Tally's normal user. Add your preferred database flags to the final command if needed.

export TALLY_URL=https://tally.example.com:8443
export TALLY_HTTP_BIND=0.0.0.0:8443
export TALLY_TLS_CERT_FILE=/absolute/path/to/fullchain.pem
export TALLY_TLS_KEY_FILE=/absolute/path/to/privkey.pem
bash install-tally.sh --port 8443

Supply a PEM full-chain certificate and its matching, unencrypted PEM private key. Both files and their parent directories must be accessible to Tally's user; keep the private key readable only by that user. The installer checks expiry, hostname, and key matching, and leaves your files intact.

Change HTTPS on an existing installation

Edit these values in ~/.config/godel-tally/tally.env (or your custom configuration file). Use literal absolute paths, without shell quotes or $HOME substitution:

TALLY_URL=https://tally.example.com:8443
TALLY_HTTP_BIND=0.0.0.0:8443
TALLY_UPGRADE_WEB_ORIGIN=https://tally.example.com:8443
TALLY_TLS_CERT_FILE=/absolute/path/to/fullchain.pem
TALLY_TLS_KEY_FILE=/absolute/path/to/privkey.pem

Restart Tally and open the configured hostname. Tally serves HTTPS directly; nginx is not required. Restart after every certificate replacement or renewal so it loads the new files.

brew install certbot

sudo apt-get update
sudo apt-get install -y certbot

sudo dnf install -y certbot

sudo "$(command -v certbot)" certonly --standalone \
  --config-dir /etc/letsencrypt \
  --cert-name tally.example.com \
  --domain tally.example.com \
  --email admin@example.com \
  --agree-tos

tally_cert_dir="$HOME/.local/share/godel-tally/tls"
mkdir -p "$tally_cert_dir"
chmod 700 "$tally_cert_dir"
sudo install -m 600 -o "$(id -u)" -g "$(id -g)" \
  /etc/letsencrypt/live/tally.example.com/fullchain.pem \
  "$tally_cert_dir/fullchain.pem"
sudo install -m 600 -o "$(id -u)" -g "$(id -g)" \
  /etc/letsencrypt/live/tally.example.com/privkey.pem \
  "$tally_cert_dir/privkey.pem"

export TALLY_URL=https://tally.example.com:8443
export TALLY_HTTP_BIND=0.0.0.0:8443
export TALLY_TLS_CERT_FILE="$HOME/.local/share/godel-tally/tls/fullchain.pem"
export TALLY_TLS_KEY_FILE="$HOME/.local/share/godel-tally/tls/privkey.pem"
bash install-tally.sh --port 8443

# Test renewal against the staging service.
sudo "$(command -v certbot)" renew --dry-run \
  --config-dir /etc/letsencrypt --cert-name tally.example.com
# Renew the real certificate when due.
sudo "$(command -v certbot)" renew \
  --config-dir /etc/letsencrypt --cert-name tally.example.com

systemctl --user restart tally-server

launchctl kickstart -k "gui/$(id -u)/ai.godel.tally.server"

Create the first account#

Open the URL printed by the installer. Inspect and accept the local self-signed certificate for evaluation, then register the first administrator. Additional accounts need invitations. Tally is self-hosted: no SaaS subscription or Gate portal account is needed to install or use it.

For access beyond this machine, follow the HTTPS setup above and use that hostname in your browser.

Installer options#

Set TALLY_VERSION=v0.1.0 before running the script to install a particular published release. Otherwise it selects the latest release.

Choose how your databases run#

Native PostgreSQL and ClickHouse are the default. Keep Tally as a native binary and choose Docker, Apple containers, or existing database servers instead. You can also mix modes or deploy the full Docker stack.

Download install-tally.sh using the command above, then choose one of the following commands instead of the default installer invocation. Decide before your first installation: switching database modes does not move existing data.

Docker databases#

Install and start Docker, then run the downloaded installer:

bash install-tally.sh --port 8443 --db docker

Only PostgreSQL and ClickHouse run in containers. Their ports bind to loopback and their data uses persistent named volumes. The Tally user service starts its managed containers before launching the application.

Apple containers#

On an Apple silicon Mac with macOS 26 or newer, install the Apple container runtime, then select it explicitly:

bash install-tally.sh --port 8443 --db apple

Tally uses the container CLI and starts its system service as needed. Database data lives in Apple container volumes. Switching from Docker to Apple container does not migrate volumes; they have separate storage.

Use existing databases#

Prepare PostgreSQL 15+ and ClickHouse 26.9+ with dedicated Tally databases. The PostgreSQL account must own its database and be able to apply migrations. The ClickHouse account needs table creation, read, and write permissions in its database.

export TALLY_POSTGRES_URL='postgres://tally:URL_ENCODED_PASSWORD@db.example.com:5432/tally?sslmode=require'
export TALLY_CLICKHOUSE_URL='https://clickhouse.example.com:8443?user=tally'
export TALLY_CLICKHOUSE_PASSWORD='REPLACE_WITH_YOUR_PASSWORD'
export TALLY_CLICKHOUSE_DATABASE=tally
bash install-tally.sh --port 8443 --db existing

Replace the example addresses and passwords. URL-encode the PostgreSQL password. Existing mode does not install, start, stop, or remove the database servers. It does apply Tally migrations inside the configured databases, so take backups before using populated databases.

Mix database modes#

For example, use an existing PostgreSQL database and a Docker-managed ClickHouse instance:

export TALLY_POSTGRES_URL='postgres://tally:URL_ENCODED_PASSWORD@db.example.com:5432/tally?sslmode=require'
bash install-tally.sh --port 8443 \
  --postgres existing \
  --clickhouse docker

Full Docker or a source build#

Clone the repository for these alternatives. make docker-up builds the Tally image and starts Tally, PostgreSQL, and ClickHouse through Compose. No separate web, collector, or nginx container is needed.

git clone https://github.com/godellabs-ai/godel-tally.git
cd godel-tally
make docker-up
# Stop the stack; retain database volumes
make docker-down

For a native source build, run make web-install, make build, then make run. The foreground runner uses Docker databases by default; TALLY_DB_MODE=apple make run selects Apple containers. See Development for toolchain requirements and live reload.