Installation

Install an Instance on Windows (as a Service or in IIS) or Linux, create the admin account, and set up HTTPS.
Framework Docs Menu

An Instance runs your TrakHound Packages: Apps, APIs, Functions, Workers, and Services. Install it on Windows as a Windows Service or into IIS, or on Linux as a systemd service. This page covers installing, upgrading, and uninstalling; see Instances and Configuration & Deployments for configuring a running Instance.

Windows Service Most Windows installs. Runs on its own port (default 8472) with the built-in web server
ASP.NET Core Runtime 10
IIS Application Windows servers that already use IIS for HTTPS, ports 80/443, or host names
Hosting Bundle 10WebSocket Protocol
Linux (systemd) x64 or Arm64 Linux. The .NET runtime is included; use a reverse proxy for HTTPS
systemdlibicu
Create the admin account, then sign in at /_admin The installers ask for it; there are no default credentials
One Windows installer covers the Windows Service and IIS, and can convert between them.

Requirements

Windows ServiceIIS ApplicationLinux
Operating system64-bit or 32-bit Windows (the installer picks the matching build)Windows with IIS installed64-bit Linux (x64 or Arm64) with systemd
RuntimeASP.NET Core Runtime 10.0, matching Windows' architectureASP.NET Core Hosting Bundle 10.0, installed after IISIncluded in the release. Needs ICU (libicu)
OtherIIS WebSocket Protocol (required) and Application Initialization (recommended)
NetworkA free TCP port (default 8472)The IIS site's bindings (ex. 443)A free TCP port (default 8472)
AccountAdministrator, to run the installerAdministrator, plus an Application Pool identity with Modify permission on the Instance foldersRoot (sudo)
The Windows installer checks for the runtime and stops with a download link if it's missing. If IIS was added after the Hosting Bundle, run the Hosting Bundle installer again and choose Repair.

Windows Service

Download the installer (trakhound-instance-<version>-install.exe) and run it as an administrator:

  1. Hosting - Choose Windows Service.
  2. Install directory - The default is C:\Program Files\TrakHound\Instance, for the program files only.
  3. Instance Port - The HTTP port for the admin UI, Apps, and APIs (default 8472). Setup warns you if another program already uses it.
  4. Admin Account - The admin username and password (each at least 4 characters).
  5. Tasks - Start Menu and Desktop icons, start the service with Windows (Automatic, Delayed Start), start it now, and, to reach the Instance from other computers, allow the port through Windows Firewall (off by default).
  6. Default Packages (new installs only) - Installs the Packages listed on the page, such as a Welcome page at / and the example Packages, each with a configuration. Untick it to start with an empty Instance, as you usually would for production.
  7. Deployment (optional) - A .thd file to set the Instance up with (see below).
  8. Ready and Finished - Setup installs and starts the service, then opens the admin UI.
ItemLocation or value
Program filesC:\Program Files\TrakHound\Instance
ConfigurationC:\ProgramData\TrakHound\Instance\config\default
PackagesC:\ProgramData\TrakHound\Instance\packages
VolumesC:\ProgramData\TrakHound\Instance\volumes
LogsC:\Program Files\TrakHound\Instance\logs
ServiceTrakHound-Instance (TrakHound Instance), runs as Local System and restarts if it fails

C:\ProgramData\TrakHound\Instance is restricted to SYSTEM and Administrators. The service finds it through the TRAKHOUND_CONFIGURATION_PATH, TRAKHOUND_PACKAGE_PATH, and TRAKHOUND_VOLUME_PATH environment variables set on the service.

IIS Application

Create the IIS site and Application Pool first, then run the installer into the site's folder. The installer doesn't create sites or pools; it installs the files and sets the data paths in the site's web.config.

1. Create the Application Pool

The Instance is a long-running server, so its pool must never idle, recycle, or overlap. In IIS Manager, add a pool for this Instance only, with these Advanced Settings:

SettingValueWhy
.NET CLR versionNo Managed CodeASP.NET Core doesn't use the .NET Framework
Enable 32-Bit ApplicationsFalse (on 64-bit Windows)Must match the installed x64 build
Start ModeAlwaysRunningStarts the pool with Windows
Idle Time-out (minutes)0The default 20 minutes would stop every Worker and Service when there's no web traffic
Regular Time Interval (recycling)0Prevents scheduled restarts
Disable Overlapped RecycleTrueTwo copies of the Instance must never run at once
Shutdown Time Limit (seconds)90 or moreThe Instance can take up to 60 seconds to stop
Load User ProfileTrue

2. Create the Site

  1. Create a folder for the site, ex. D:\Sites\TrakHound.
  2. Add a website using that folder and the new pool, with the bindings you need (ex. https on 443 with your certificate).
  3. In the site's Advanced Settings, set Preload Enabled to True (needs Application Initialization).
  4. Give the pool identity (IIS AppPool\<pool name>) Modify permission on the site folder.

Host the Instance at the root of the site, not in a virtual directory or sub-application.

3. Run the Installer

  1. On the Hosting page, choose IIS Application, and select the site's folder as the install directory.
  2. Enter the Admin Account, choose whether to install the Default Packages on a new install, and optionally select a Deployment file. The Port and Tasks pages are skipped; the site's bindings set the address.
  3. The Ready page lists the folders the pool identity needs Modify permission on.
  4. Browse to the site (ex. https://trakhound.example.com/_admin). The Instance starts on the first request, or when the pool starts if Preload is enabled.

Configuration, Packages, and Volumes are stored in config, packages, and volumes inside the site folder. Setup keeps an existing web.config and only changes its TrakHound paths. The shipped web.config runs in-process, allows 5 minutes for startup, and lifts IIS's 30 MB upload limit so the Instance's own Max Request Size (256 MB) applies.

The separate Admin port isn't available under IIS. If the site is public, restrict /_admin with IIS IP and Domain Restrictions.

Linux

The Linux release is an archive for each architecture, trakhound-instance-<version>-linux-x64.tar.gz and -linux-arm64.tar.gz (uname -m shows x86_64 or aarch64). It includes the .NET runtime and an install.sh script that installs, upgrades, and uninstalls the Instance as a systemd service:

tar xzf trakhound-instance-<version>-linux-x64.tar.gz
sudo bash trakhound-instance/install.sh

install.sh then:

  1. Checks the archive matches the machine's architecture and that ICU is installed (from your distribution's libicu package, ex. libicu74 on Ubuntu 24.04 or libicu72 on Debian 12).
  2. Creates the trakhound system user, which can't sign in.
  3. Copies the program files and creates the data folder, which only the trakhound user can open.
  4. Asks for the admin username and password, if no account exists.
  5. Installs, enables, and starts the trakhound-instance service, and waits until the Instance is ready.
OptionWhat it does
--port <port>HTTP port for a new install (default 8472). An upgrade keeps the configured port
--admin-user <name>Creates an Owner admin account, or sets the password of the account with that username. The password is asked for, or read from standard input when it's redirected
--admin-password-file <file>Reads the admin password from the first line of a file
--deployment <file.thd>A deployment to install when the Instance starts
--no-startInstalls without starting the service
--uninstallRemoves the service and program files, and keeps the data
--purgeWith --uninstall, also deletes the data and the trakhound user

An unattended install on port 9000, with the admin account and a deployment:

sudo bash trakhound-instance/install.sh --port 9000 --admin-user admin --admin-password-file /root/trakhound-admin.txt --deployment site-a-1.0.0.thd
ItemLocation or value
Program files/opt/trakhound/instance
Configuration/var/lib/trakhound/instance/config/default
Packages/var/lib/trakhound/instance/packages
Volumes/var/lib/trakhound/instance/volumes
Logs/opt/trakhound/instance/logs, and the systemd journal
Servicetrakhound-instance, runs as the trakhound user and restarts if it fails
  • Firewall - To reach the Instance from other computers, open the port (ex. sudo ufw allow 8472/tcp, or sudo firewall-cmd --permanent --add-port=8472/tcp and sudo firewall-cmd --reload). Skip this behind a reverse proxy.
  • Status and logs - systemctl status trakhound-instance, and journalctl -u trakhound-instance -f to follow its output.
  • Service settings - install.sh replaces the service file on every install and upgrade. To add a setting such as an environment variable, use sudo systemctl edit trakhound-instance, which keeps your change in a separate file.
  • Packages must run on Linux: a Package that uses Windows-only features (ex. the Windows Registry) doesn't load.

Admin Account

The first admin account is created on the machine the Instance runs on, never in the browser, so whoever reaches a new Instance first can't claim it. There are no default credentials. This account is an Owner, which adds the other admin accounts and chooses their roles on Security > Admin Accounts (see Admin Accounts and Roles). The installers ask for it; otherwise, or to get back in when no Owner can sign in, run set-admin from the program folder. With a new username it adds an Owner, and with an existing one it sets that account's password, enables it, and makes it an Owner. It asks for the password, and takes effect within a few seconds:

# Windows Service (from an administrator prompt)
"C:\Program Files\TrakHound\Instance\TrakHound.Instance.exe" set-admin admin --configurationPath "C:\ProgramData\TrakHound\Instance\config"

# Linux
sudo -u trakhound /opt/trakhound/instance/TrakHound.Instance set-admin admin --configurationPath /var/lib/trakhound/instance/config

For scripted installs, the Windows installer takes /ADMINUSER= with /ADMINPASSWORDFILE= (the first line of a file), and the Instance creates the account when it starts from TRAKHOUND_ADMIN_USERNAME and TRAKHOUND_ADMIN_PASSWORD_FILE if none exists. Then open http://<server>:8472/_admin and sign in. Admin sessions last 7 days and survive restarts.

The device-id Command

Licenses are issued for a Device ID. On an Instance without the admin UI (ex. a device with no screen), device-id shows it so you can request a license for that device. It writes only the ID to standard output, so a script can read it, and --json also says where it came from:

id=$(/opt/trakhound/instance/TrakHound.Instance device-id)
TrakHound.Instance device-id --json

The Device ID comes from the machine name, so renaming the device changes it. In a container it comes from TRAKHOUND_DEVICE_ID. The Instance also writes it to its log when it starts.

HTTPS with a Reverse Proxy

The Windows Service and Linux Instance serve HTTP. To serve HTTPS or ports 80 and 443, put a reverse proxy such as nginx, Apache, Caddy, or IIS in front of it:

  1. Set HTTP Address to 127.0.0.1 (Settings > Interfaces, or httpAddress) so the Instance only accepts connections from the proxy on the same server.
  2. Add the proxy's address to Trusted Proxies (trustedProxies). The Instance then takes the client's address from X-Forwarded-For and the scheme from X-Forwarded-Proto, so logs, Rate Limits, and the same-machine checks see the real client.
  3. Forward the whole site with those headers, allow WebSockets (the admin UI and Apps use them), and lift the proxy's upload limit.
map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

server {
    listen 443 ssl;
    server_name trakhound.example.com;
    ssl_certificate     /etc/ssl/certs/trakhound.example.com.crt;
    ssl_certificate_key /etc/ssl/private/trakhound.example.com.key;
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:8472;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 1h;
    }
}

Silent Installs and Startup Deployments

The Windows installer takes command-line options for unattended installs (run from an administrator prompt):

OptionWhat it does
/VERYSILENT, /SUPPRESSMSGBOXESNo wizard or progress window (/SILENT shows progress), and default answers to message boxes
/HOSTING=Service or /HOSTING=IISThe hosting type. Default: the installed version's, or Service
/DIR="path"Install directory (the site's folder for IIS)
/PORT=8472HTTP port, for new Windows Service installs
/TASKS="..."Comma separated: startmenuicon, desktopicon, autostart, startservice, firewall. Tasks not listed are off
/ADMINUSER=, /ADMINPASSWORDFILE=The admin account, with its password read from the first line of a file
/DEFAULTPACKAGES=noDon't install the default Packages. New installs install them, with their configurations, unless this is set
/DEPLOYMENT="path"A deployment file (.thd) to install when the Instance starts
/LOG="path"Writes a Setup log to the file
trakhound-instance-<version>-install.exe /VERYSILENT /SUPPRESSMSGBOXES /HOSTING=Service /PORT=9000 /TASKS="autostart,startservice,firewall" /ADMINUSER=admin /ADMINPASSWORDFILE="C:\Setup\admin.txt" /DEPLOYMENT="C:\Setup\site-a-1.0.0.thd"

A startup deployment sets up a new Instance with known configurations and Packages. Create one on an Instance that's already set up (Deploy > Create, or th deployments create); Setup copies it to the Instance's deployments folder, and the Instance installs it when it starts, before it reads its configuration. It backs up first and restores the backup if the install fails, and each file is installed only once. See Configuration & Deployments.

Make startup deployments without Include Secrets, and use Configuration Variables for values that differ per site. Without Include Secrets, Deployments don't carry admin accounts.

Upgrading and Converting

To upgrade, run the newer installer (or the newer release's install.sh on Linux). It keeps the hosting type, install directory, configuration, Packages, Volumes, port, and admin account.

HostingDuring an upgrade
Windows ServiceStops the service (up to 60 seconds), replaces the files, and starts it again
IIS ApplicationTakes the site offline with app_offline.htm (up to 90 seconds), replaces the files, and brings it back; the Instance starts on the next request
LinuxStops the service, replaces the program and service files, and starts it again

To convert between a Windows Service and IIS, run the installer and choose the other hosting type. If the Instance has run, its configuration, Packages, and Volumes stay where they are and the new hosting type is pointed at them:

  • Service to IIS - Set up the site and pool first. Setup removes the service, and the site's web.config points at C:\ProgramData\TrakHound\Instance, so give the pool identity Modify permission on that folder.
  • IIS to Service - Setup takes the site offline with app_offline.htm and leaves it offline, so IIS doesn't run a second copy. Remove the site and pool from IIS afterwards.

Uninstalling

  • Windows - In Settings > Apps > Installed apps, uninstall TrakHound Instance. Setup asks whether to also delete the data (choose No to keep it for a reinstall). It removes a Windows Service and its firewall rule; for IIS, it takes the site offline and removes the program files, and the site and pool stay for you to remove.
  • Linux - sudo bash trakhound-instance/install.sh --uninstall removes the service and program files and keeps the data in /var/lib/trakhound/instance. Add --purge to also delete the data and the trakhound user.

Troubleshooting

Start with the Instance's logs folder, the Setup log in %TEMP% and Event Viewer on Windows, or systemctl status trakhound-instance and journalctl -u trakhound-instance on Linux.

ProblemWhat to do
"Windows protected your PC" (SmartScreen)Click More info, then Run anyway
Setup says the ASP.NET Core Runtime or Hosting Bundle is requiredInstall the 10.0 version from the link Setup offers, then run Setup again
Setup warns that the port is in useChoose another port, or stop the other program. netstat -ano shows which process uses it
The service installs but doesn't startCheck the Instance logs and Event Viewer. Common causes are a port in use or an error in instance.config.yaml
The admin UI doesn't open from another computerAllow the port through the firewall, and check that httpAddress isn't 127.0.0.1
IIS: HTTP Error 500.19IIS can't read web.config. Install (or Repair) the ASP.NET Core Hosting Bundle
IIS: HTTP Error 500.30 or 500.31The Instance failed to start or can't find the runtime. Check the Hosting Bundle version, Event Viewer, and the pool identity's Modify permission on the site and data folders
IIS: admin pages load but don't respondInstall the IIS WebSocket Protocol feature
IIS: Workers stop after a whileThe pool is idling or recycling. Set Idle Time-out and Regular Time Interval to 0, and Start Mode to AlwaysRunning
IIS: the site says it's being updated after Setup finishedDelete app_offline.htm from the site folder (left on purpose after converting to a Windows Service or uninstalling)
Linux: "ICU was not found"Install your distribution's libicu package, then run install.sh again
Linux: the release "isn't built for this machine"Download the archive for the server's architecture: linux-x64 for x86_64, linux-arm64 for aarch64
Linux: the service fails with status=203/EXEC or "Access to the path is denied"Run install.sh again: it restores the program files and resets the folders' owner
Linux: systemctl status shows activating, then a timeoutThe Instance didn't finish starting within 5 minutes. Check journalctl -u trakhound-instance
Behind a proxy, logs show the proxy's address, or admin pages don't respondAdd the proxy to Trusted Proxies and send X-Forwarded-For, and pass WebSockets (the Upgrade and Connection headers)
The sign-in page says "No Admin Account"Create one with set-admin (see Admin Account)
A "Previous Run did not Shut Down Cleanly" notificationOpen the Instance's Information tab: Last Shutdown shows the reason, and Shutdown Details shows the exception and, on Windows, the Event Log entries (see Boot History)
The Instance takes a long time to start, or logs errors while startingOpen the Instance's Boots tab and click the run. Each startup step shows how long it took, the step that failed, and the warnings and errors logged while starting
To script an Instance's setup after installing it, use the CLI: th packages install installs Packages, th config adds configurations and variables, th instance set changes settings such as the HTTP port, and th config validate checks the result.