Installation of TrixOS

This guide installs the panel (control server). Site agents are installed later from inside the panel, see Site Agents. Check the system requirements first.

Install with the script

On a fresh Ubuntu 22.04 / 24.04 or Debian 12 / 13 server (x86_64, at least 2 GB RAM), as root:

curl -fsSL https://trixos.sh/install | bash

With HTTPS on your own name (recommended; the DNS record must point to the server and ports 80 and 443 must be free and reachable):

curl -fsSL https://trixos.sh/install | bash -s -- --domain panel.example.com --email [email protected]

With a Pro or Enterprise key:

curl -fsSL https://trixos.sh/install | bash -s -- --key TRX-XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

You can read the script before you run it.

What the script does

1. Checks the system: root, x86_64, a supported Ubuntu or Debian release, at least 2 GB RAM.
2. Installs curl, ca-certificates, openssl, tar and iproute2, and Docker with the Compose plugin if it’s missing.
3. Downloads the newest release from https://trixos.sh/releases/ and verifies it before unpacking anything: the signed release record (trixos-X.Y.Z.tar.gz.sig) must carry a valid Ed25519 signature from the release key built into the script, and the package must match the SHA-256 in that record. An unsigned or altered release is refused. The package contains the built application only, no source code.
4. Unpacks it into /opt/trixos. It only installs into an empty directory or over an existing TrixOS installation, and never over a newer version (the database can’t be downgraded).
5. On a new installation, writes /opt/trixos/.env with fresh secrets: TRIXOS_MASTER_KEY, TRIXOS_SESSION_SECRET and a database password. It sets the panel URL, the port and, with --key, the license key. With --domain it turns on the built-in HTTPS (below).
6. Builds and starts the containers with Docker Compose and waits until the API answers.
7. On a new installation, creates the user admin and prints its password once.

At the end it prints the panel’s address, for example https://panel.example.com (or http://203.0.113.10:8088 without --domain, with a warning), the user name and the password.

Back up .env

TRIXOS_MASTER_KEY in /opt/trixos/.env encrypts every BMC, switch and webhook secret and every root password of a running job. Without it, a database backup can’t be decrypted. Store .env in your password manager.

Options

Option	Default	Meaning
--domain NAME	none	Serve the panel over HTTPS on this name with a Let’s Encrypt certificate (HTTPS)
--email ADDRESS	none	Contact address for the Let’s Encrypt account (optional)
--key TRX-…	none	Activate this Pro or Enterprise key on start (TRIXOS_LICENSE_KEY)
--dir PATH	/opt/trixos	Installation directory
--url URL	https://<domain>, else http://<server IP>:<port>	Public address of the panel (TRIXOS_PUBLIC_URL)
--port PORT	8088	HTTP port of the panel (behind the built-in HTTPS: on 127.0.0.1 only)
--version X.Y.Z	newest	Install a specific release
--allow-downgrade	off	Allow --version older than the installed one. The database is not downgraded: only with a backup
--download-only DIR	off	Download and verify the release, unpack it into DIR and stop (nothing is installed)

Every option can also be given as an environment variable: TRIXOS_DOMAIN, ACME_EMAIL, TRIXOS_LICENSE_KEY, TRIXOS_DIR, TRIXOS_PUBLIC_URL, TRIXOS_PORT, TRIXOS_VERSION.

Where things live

Path	What
/opt/trixos	The release: docker-compose.yml, Dockerfile, the built application, VERSION
/opt/trixos/.env	Your configuration and secrets (kept on updates)
/opt/trixos/isos	Custom ISOs (kept on updates)
Docker volumes	The database, Redis and the boot-file cache (kept on updates)

Manage the containers from the installation directory:

cd /opt/trixos
docker compose ps
docker compose logs -f api
docker compose exec api trixos license status

For the graphical console of BMCs whose KVM needs Java or a vendor viewer, build the viewer image once: docker compose --profile tools build kvm-viewer. The viewer service that starts these containers has no access to Docker itself: the docker-proxy service holds the Docker socket and lets through only viewer containers (Security).

Update

Run the script again. It downloads and verifies the newest release, replaces the release files, keeps .env, isos and all data, and restarts the containers; database migrations run on start. Add --domain to turn on HTTPS for an existing installation. Or update with one click in the panel. See Platform Updates.

Live mode

The script configures the panel for real hardware (TRIXOS_ALLOW_DESTRUCTIVE=true): power actions and installs reach the BMCs as soon as you add servers. To try TrixOS without touching hardware, set it to false in .env and run docker compose up -d; see Safety switches.

HTTPS

Built in (--domain)

With --domain panel.example.com the installer adds a Caddy container (compose profile https) on the server’s ports 80 and 443. It gets and renews a Let’s Encrypt certificate for that name, redirects HTTP to HTTPS, sends HSTS and forwards to the panel. The panel’s own port (8088) then listens on 127.0.0.1 only, so the only way in is HTTPS. Before you run it:

• a DNS record for the name points to the server (with Cloudflare in front: SSL mode Full (strict)),
• ports 80 and 443 are free on the server and reachable from the internet (Let’s Encrypt checks port 80).

The settings it writes to .env:

COMPOSE_PROFILES=https
TRIXOS_DOMAIN=panel.example.com
ACME_EMAIL=[email protected]          # optional
TRIXOS_PUBLIC_URL=https://panel.example.com
WEB_BIND_ADDRESS=127.0.0.1           # the panel's port on localhost only
TRIXOS_REAL_IP_FROM=local            # believe X-Forwarded-For only from this host (Caddy)

docker compose logs https shows the certificate requests. The certificates are kept in the Docker volume caddydata.

Your own reverse proxy

To use a proxy you already run (nginx, Traefik, a load balancer), install without --domain and set in .env:

• the proxy on the same host: WEB_BIND_ADDRESS=127.0.0.1 and TRIXOS_REAL_IP_FROM=local,
• the proxy on another machine: TRIXOS_REAL_IP_FROM=<its address> (several separated by spaces) and a firewall rule so that only the proxy reaches port 8088,

then TRIXOS_PUBLIC_URL=https://panel.example.com and docker compose up -d. The proxy must set X-Forwarded-For to the client’s address and should hide /metrics (no authentication). Login throttling, console links (bound to the client’s address) and the audit log rely on it. Without a proxy (TRIXOS_REAL_IP_FROM=none, what the installer sets) clients can’t fake their address, but the panel speaks plain HTTP: the installer warns about that.

Activate your license

Open the panel, sign in as admin and open Settings → License. Until a license is active the panel shows only that page. Activate the free Community Edition (up to 10 servers) with your e-mail address, or enter your license key. See Licensing.

Then change the admin password under Profile & security (the menu under your name, top right) and continue with the Quick Start Guide.

From source (early access partners)

Early access partners with access to the repository can run TrixOS from source with Docker Compose:

apt-get install -y docker.io docker-compose git openssl
git clone <repository> /opt/trixos && cd /opt/trixos
cp .env.example .env && chmod 600 .env
sed -i "s|^TRIXOS_MASTER_KEY=.*|TRIXOS_MASTER_KEY=$(openssl rand -base64 32)|; \
        s|^TRIXOS_SESSION_SECRET=.*|TRIXOS_SESSION_SECRET=$(openssl rand -hex 32)|" .env

Edit .env and set at least TRIXOS_PUBLIC_URL, POSTGRES_PASSWORD (a long random password), VIEWER_SECRET (openssl rand -hex 32) and PXE_HTTP_BASE. Every setting is listed in the configuration reference. Then:

mkdir -p isos && chown 1000:1000 isos
docker compose up -d --build
docker compose --profile tools build kvm-viewer
docker compose exec api node --import tsx apps/api/src/cli/create-user.ts --username admin --role admin

The last command prints a generated password. A source installation starts in dry-run mode (TRIXOS_ALLOW_DESTRUCTIVE=false). Updates: git pull --ff-only && docker compose up -d --build.

The repository also contains systemd units (deploy/systemd) and an nginx configuration for a bare-metal install with Node.js 22, Postgres and Redis from the distribution. The Docker Compose setups are the supported ones.