Installing self-hosted

Self-hosted Tenvara is one Docker Compose install per MSP, on a server you run: in your office, your data centre or your cloud account. It is the same product as hosted, with the same features.

What you need#

• A Linux server with Docker and Docker Compose v2. See How big a server below.
• A DNS name for the install, for example support.yourmsp.co.uk, pointing at the server.
• Ports 80 and 443 reachable from the internet, so the built-in Caddy can get a certificate and agents can connect.
• Your licence file (.tvl) and the registry pull token that comes with it. Self-hosted is available by beta invitation for now (see Joining the beta); when you're invited with a self-hosted licence, you get both from us.
• Outgoing HTTPS from the server to the internet, so the installer can download the signed images and the install can check in with the licence server once a day. For a server that cannot reach the internet, ask us for an offline licence: see Licence and updates.

Optional, depending on what you use:

• UDP 3478 and 49160 to 49200 if remote sessions need the built-in relay (devices behind strict NAT), and a DNS record turn.<your domain> pointing at the server so the relay also works over TLS on port 443 for networks that only allow web traffic.
• Port 514 (UDP and TCP) from your firewalls and network devices, if they send syslog to Security. Syslog has no sign-in, so it is only accepted on the server itself until you set SYSLOG_BIND in .env to the server's private or VPN address. Never publish it to the internet.
• Port 25, if you point your own support domain's mail at the server (Settings > Support email, Inbound address).
• Ports 28100 to 28199, if technicians open device web pages through an agent and the install gives each session a port of its own (used when no wildcard name is set up for the install). See Opening device web pages.
• An SMTP server for outgoing email.

How big a server#

The installer looks at the server's CPUs and memory and picks an install profile, which sizes the database, the monitoring history store, the backup service and the background workers to fit:

The profile is picked again on every update, so a resized server gets its new profile by itself. To choose your own, set TENVARA_INSTALL_PROFILE to small, standard or large in .env. Settings > System status shows the table with your install's row marked.

What runs#

The Compose file starts these services:

Install#

1. Run the installer#

Put the installer (install.sh) and your licence file on the server, then run:

./install.sh --licence tenvara.tvl --pull-token <your pull token> --domain support.yourmsp.co.uk

Leave out any of the three and the installer asks for it. The installer:

1. Checks Docker, Docker Compose v2 and curl are there.
2. Signs in to the Tenvara image registry with your licence and pull token.
3. Checks the signature of every image against the Tenvara signing key before anything is started, and pins each image by its digest. If one image does not check out, it stops before writing or starting anything.
4. Writes the settings file, .env, with new random secrets for every password and key the services share, and the install profile it picked.
5. Starts the stack, waits until it is healthy, installs your licence and checks in with the licence server.
6. Prints the address to open and the command that creates the first administrator.

It installs into /opt/tenvara by default (--dir chooses another folder). It is safe to run again: an existing install keeps its own secrets and settings. ./install.sh --help lists every option, including --http-port, --https-port and --site-address for running behind another proxy, and --channel to choose between stable and beta versions.

On every start the core container brings the database up to date, sets up the default roles and modules (existing ones are never changed), creates its token signing key if there is none, and prepares the monitoring tables. The background work, scheduler and websocket services wait until it is healthy, so they never race it. The first start takes a few minutes while images download.

Check everything is up from the install folder:

docker compose ps

2. Create the first administrator#

When the installer finishes, it prints the address to open and the exact command that creates the first administrator, already filled in with your install's folder and project name. Copy that command and run it, then follow the prompts for the email address, name and password. Passwords are at least 12 characters. Then open https://<your domain> and sign in. Set up two-factor straight away, from the account menu, Password and two-factor.

A new install starts with the service desk switched on. Everything else your licence includes is one click away in Settings > Modules, and the installer says so when it finishes. See Switching modules on.

3. Check the licence#

Go to Settings > Licence. It shows your edition, what your licence covers, your usage against any limits, and the last check-in. The install checks in once a day with counts only (never customer data) and gets a fresh 14-day lease. If check-ins fail for a while, Tenvara warns you, then becomes read-only rather than stopping: nothing is ever deleted because of the licence. See Licence and updates.

Tip: To try Tenvara on your own machine first, use --domain localhost. Caddy then uses its own local certificate, which your browser will warn about.

Settings in .env#

Every install setting lives in .env in the install folder, and Tenvara's own settings all start with TENVARA_. Run docker compose up -d again after changing the file.

Note: If your .env was written by an older installer, some settings carry an older prefix. An update stops before changing anything and names the settings to rename. Rename them, then run the update again.

Behind another proxy#

If something in front of the server already handles TLS (a load balancer or reverse proxy), tell Caddy to answer plain HTTP and tell Tenvara the address people really use:

TENVARA_SITE_ADDRESS=http://support.yourmsp.co.uk   # or :80 to answer on any hostname
APP_URL=https://support.yourmsp.co.uk

An install set up this way keeps answering plain HTTP after every update, so your proxy goes on working.

To try it locally on a spare port, for example: HTTP_PORT=8480, TENVARA_SITE_ADDRESS=http://localhost and APP_URL=http://localhost:8480.

Agents pin the certificate your server presents, so they refuse anything in the middle that swaps it. When something else ends TLS in front of the server, set TENVARA_AGENT_TLS_PROBE and, if needed, TENVARA_AGENT_TLS_PINS so agents learn the right certificate. A proxy that inspects TLS on your customers' networks must leave the server's address out of inspection.

Email#

Until SMTP is set up, Tenvara sends nothing. Each message (password resets, portal sign-in links and invitations, notifications) is written as an .eml file to storage/app/dev-mail on the core-storage volume instead. That is fine while you try things out; set up SMTP before anyone relies on email:

MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_FROM_ADDRESS=support@yourmsp.co.uk
MAIL_FROM_NAME="Your MSP"

Run docker compose up -d again after changing .env.

Remote control behind strict NAT#

Remote sessions connect the browser and the device directly when they can. Where they cannot, turn on the built-in relay:

TENVARA_TURN_ENABLED=1
TENVARA_TURN_PUBLIC_IP=203.0.113.10
TENVARA_TURN_SECRET=          # a long random string

and open UDP 3478 and 49160 to 49200 to the server. The relay over TLS on 443 uses turn.<your domain> (or the name in TENVARA_TURN_TLS_HOST): add the DNS record and its certificate is issued by itself. Settings > Remote access, the Relay tab, says when the relay is not working and why. It checks the relay's name against public DNS (Cloudflare's and Google's resolvers, over HTTPS first), so a name your server resolves to an internal address is judged by what viewers outside see. A server that cannot reach public DNS shows Not checked with the reason: list a resolver it can reach in TENVARA_PUBLIC_DNS.

Sign-in#

Local accounts (email and password, with two-factor you can require) work with nothing else set. Single sign-on is set up in the app, not in .env: see Single sign-on. Keep at least one break-glass administrator who can sign in with a password if the identity provider is ever down.

Back up the server#

Your data lives in named Docker volumes. Back these up somewhere other than this server:

Warning: Without keys.json no backup taken by Tenvara can ever be read, and the backup service refuses to start rather than make a new key. Keep a copy of the backup-data volume, or at least keys.json, off the server. Settings > Backup, the Status tab, shows the key's fingerprint, and Download a recovery copy there gives you the key sealed with a passphrase you choose, with Check my copy to prove the copy opens. See Recovery copy of the encryption key.

The other volumes (redis-data, minio-data, caddy-data, caddy-config, vector-data, security-enrichment, remote-data, clamav-data and mailin-data) hold caches, certificates, queued mail and backup repositories. Every backup also carries its own catalogue, so a new server given the storage and the keys can rebuild the catalogue. Back up minio-data too if your backup repositories live in the bundled MinIO.

Upgrading#

You upgrade when it suits you. Settings > Updates shows the newest version your licence covers, with its release notes.

1. Back up the volumes above.

2. Read the release notes for the new version. Some releases add or rename a setting in .env; the update stops before changing anything and names what it needs.

3. Run the installer with --upgrade, from the folder you installed from:

   ./install.sh --upgrade
   

   Add --version 1.2.0 to choose a version rather than the newest.

The installer checks every new image's signature before it starts anything, keeps your secrets and settings, and restarts the stack. The database is brought up to date first, in a step of its own: if that step fails, the update stops, the version you were running is put back and started healthy, and the message names what failed. An update never switches a module off. If device backups or restores are running, it waits for them first (up to 30 minutes, set in Settings > Updates), and any that are still interrupted carry on from where they stopped afterwards. If it cannot write a file it needs, it stops before changing anything and names the file and the fix. People are signed out for a few minutes while Tenvara restarts. Agents update themselves to the new release if Update agents automatically is on in Devices and agent.

Next steps#

Go to First steps to start the setup helper, add your first customer, invite your team and install the agent. Its Install and licence section checks the install for you. Install settings and profiles lists the settings an administrator meets, and Updates covers updating in more detail.