# Installation

> Install an Instance on Windows (as a Service or in IIS) or Linux, create the admin account, and set up HTTPS.

URL: https://www.trakhound.com/docs/trakhound-framework/installation

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](https://www.trakhound.com/docs/trakhound-framework/instances) and [Configuration & Deployments](https://www.trakhound.com/docs/trakhound-framework/configuration) for configuring a running Instance.

Diagram: Three ways to install an Instance. A Windows Service is best for most Windows servers and serves its own port. An IIS Application suits Windows servers that already use IIS for HTTPS, ports 80 and 443, or host names. A Linux systemd service runs on x64 or Arm64 Linux with the .NET runtime included.

## Requirements

|  | Windows Service | IIS Application | Linux |
| --- | --- | --- | --- |
| **Operating system** | 64-bit or 32-bit Windows (the installer picks the matching build) | Windows with IIS installed | 64-bit Linux (x64 or Arm64) with systemd |
| **Runtime** | [ASP.NET Core Runtime 10.0](https://dotnet.microsoft.com/download/dotnet/10.0), matching Windows' architecture | ASP.NET Core **Hosting Bundle** 10.0, installed *after* IIS | Included in the release. Needs ICU (`libicu`) |
| **Other** |  | IIS **WebSocket Protocol** (required) and **Application Initialization** (recommended) |  |
| **Network** | A free TCP port (default `8472`) | The IIS site's bindings (ex. 443) | A free TCP port (default `8472`) |
| **Account** | Administrator, to run the installer | Administrator, plus an Application Pool identity with Modify permission on the Instance folders | Root (`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](https://applications.trakhound.com/TrakHound.Instance/latest/download?prerelease=true&source=website) (`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](https://www.trakhound.com/docs/trakhound-framework/first-party-packages#examples), 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](https://www.trakhound.com/docs/trakhound-framework/installation#silent)).
8. **Ready** and **Finished** - Setup installs and starts the service, then opens the admin UI.

| Item | Location or value |
| --- | --- |
| Program files | `C:\Program Files\TrakHound\Instance` |
| Configuration | `C:\ProgramData\TrakHound\Instance\config\default` |
| Packages | `C:\ProgramData\TrakHound\Instance\packages` |
| Volumes | `C:\ProgramData\TrakHound\Instance\volumes` |
| Logs | `C:\Program Files\TrakHound\Instance\logs` |
| Service | `TrakHound-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:

| Setting | Value | Why |
| --- | --- | --- |
| .NET CLR version | No Managed Code | ASP.NET Core doesn't use the .NET Framework |
| Enable 32-Bit Applications | False (on 64-bit Windows) | Must match the installed x64 build |
| Start Mode | AlwaysRunning | Starts the pool with Windows |
| Idle Time-out (minutes) | 0 | The default 20 minutes would stop every Worker and Service when there's no web traffic |
| Regular Time Interval (recycling) | 0 | Prevents scheduled restarts |
| Disable Overlapped Recycle | True | Two copies of the Instance must never run at once |
| Shutdown Time Limit (seconds) | 90 or more | The Instance can take up to 60 seconds to stop |
| Load User Profile | True |  |

### 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.

| Option | What 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-start` | Installs without starting the service |
| `--uninstall` | Removes the service and program files, and keeps the data |
| `--purge` | With `--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
```

| Item | Location 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 |
| Service | `trakhound-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](https://www.trakhound.com/docs/trakhound-framework/security#admin-accounts)). 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):

| Option | What it does |
| --- | --- |
| `/VERYSILENT`, `/SUPPRESSMSGBOXES` | No wizard or progress window (`/SILENT` shows progress), and default answers to message boxes |
| `/HOSTING=Service` or `/HOSTING=IIS` | The hosting type. Default: the installed version's, or Service |
| `/DIR="path"` | Install directory (the site's folder for IIS) |
| `/PORT=8472` | HTTP 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=no` | Don'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](https://www.trakhound.com/docs/trakhound-framework/configuration#startup-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.

| Hosting | During an upgrade |
| --- | --- |
| Windows Service | Stops the service (up to 60 seconds), replaces the files, and starts it again |
| IIS Application | Takes 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 |
| Linux | Stops 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.

| Problem | What to do |
| --- | --- |
| "Windows protected your PC" (SmartScreen) | Click **More info**, then **Run anyway** |
| Setup says the ASP.NET Core Runtime or Hosting Bundle is required | Install the 10.0 version from the link Setup offers, then run Setup again |
| Setup warns that the port is in use | Choose another port, or stop the other program. `netstat -ano` shows which process uses it |
| The service installs but doesn't start | Check 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 computer | Allow the port through the firewall, and check that `httpAddress` isn't `127.0.0.1` |
| IIS: HTTP Error 500.19 | IIS can't read `web.config`. Install (or Repair) the ASP.NET Core Hosting Bundle |
| IIS: HTTP Error 500.30 or 500.31 | The 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 respond | Install the IIS **WebSocket Protocol** feature |
| IIS: Workers stop after a while | The 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 finished | Delete `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 timeout | The 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 respond | Add 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](https://www.trakhound.com/docs/trakhound-framework/installation#admin-account)) |
| A "Previous Run did not Shut Down Cleanly" notification | Open 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](https://www.trakhound.com/docs/trakhound-framework/instances#boots)) |
| The Instance takes a long time to start, or logs errors while starting | Open 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](https://www.trakhound.com/docs/trakhound-framework/cli#config): `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.
