> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wirekite.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Pick the Wirekite installation path that fits your environment.

Wirekite ships in three delivery paths. All three share the same binaries,
the same UI, and the same source/target support — they differ only in **who
operates the host** and **what runs as the supervisor** (systemd, Docker
runtime, or our cloud).

## Choose a path

<CardGroup cols={3}>
  <Card title="On-Prem" icon="server" href="/run/installation/onprem">
    Run on your own Linux host with a self-extracting installer. Wirekite
    is managed by systemd. Best when you want full control of the host and
    network.
  </Card>

  <Card title="Docker" icon="docker" href="/run/installation/container">
    Run as a single Docker container on your host. No systemd; the container
    runtime is the supervisor. Best when you already run a Docker-based ops
    stack or want a minimal-touch deploy.
  </Card>

  <Card title="Cloud" icon="cloud" href="/run/installation/cloud">
    We host Wirekite on a dedicated VM in our infrastructure. You get a URL,
    sign in, start migrating. Nothing to install. Best when you want a fully
    managed path.
  </Card>
</CardGroup>

## At-a-glance comparison

|                       | **On-Prem**                      | **Docker**                                         | **Cloud**                  |
| --------------------- | -------------------------------- | -------------------------------------------------- | -------------------------- |
| Who owns the host     | You                              | You                                                | Wirekite                   |
| Artifact you receive  | `wirekite-installer.run`         | Image tag on Docker Hub (or `.tar` for air-gapped) | A URL                      |
| Supervisor            | `systemd`                        | Docker runtime                                     | `systemd` (on our VM)      |
| TLS by default        | Self-signed CA                   | Self-signed CA                                     | Let's Encrypt wildcard     |
| License delivery      | You install at setup             | You bind-mount the pair                            | We install at provisioning |
| Upgrade model         | Re-run `.run`                    | `docker rm -f` + new `--image-tag`                 | Coordinated VM rebuild     |
| API server (`:9443`)  | Optional (`--with-api` at build) | Disabled                                           | Disabled                   |
| Source/target support | Full                             | Full                                               | Full                       |
| Caps + metering       | Enforced                         | Enforced                                           | Enforced                   |

The data plane is identical across all three. A migration that works on
on-prem will work the same way on Docker or cloud.

## Shared invariants

Regardless of which path you pick:

1. **One config file.** Every Wirekite binary reads `/etc/wirekite/wirekite.cfg`
   (inside the container for Docker, on the VM for cloud). No environment
   variables for runtime knobs.
2. **License is mandatory at startup.** Every binary validates
   `$WIREKITE_HOME/license/wirekite.{license,key}` and refuses to start
   without a valid pair.
3. **The `wirekite` system user owns runtime state.** UID/GID `999` is created
   at install (or pre-existing in the Docker image).
4. **Encryption key is per-host, never shared.** Each install/container/VM
   generates its own `instance/encryption.key` on first run and refuses to
   overwrite it.
5. **Web UI is on `:8443`.** Mapped to host port `:8443` by default for
   Docker; routed via `:443` at the edge for cloud.

***

## License management

License operations are identical across all three paths once installed.

### License files

A Wirekite license consists of two files:

<ResponseField name="wirekite.license" type="file">
  Encrypted license file containing customer name, expiration date, feature
  flags, and optional host binding and usage caps. The file is AES-256
  encrypted and signed with HMAC-SHA256 to prevent tampering.
</ResponseField>

<ResponseField name="wirekite.key" type="file">
  Decryption key used to read the license file. Must be paired with the
  matching `.license` file.
</ResponseField>

### How license validation works

Every Wirekite binary validates the license at startup, before doing anything
else. If validation fails, the binary prints an error and exits with code 1.
The following checks are performed:

| Check                                          | Error Message                                     |
| ---------------------------------------------- | ------------------------------------------------- |
| License file exists and is readable            | `License check fail: failed to read license file` |
| Signature is valid (file not tampered with)    | `license file has been tampered with`             |
| License has not expired                        | `License has expired`                             |
| System clock is not set before the issued date | `License issued date is in the future`            |
| MAC address matches (if host-bound)            | `Host ID mismatch`                                |

<Note>
  In the **cloud** path, MAC and clock checks are skipped (cloned VMs cannot
  have stable MACs and time may be re-synced after boot). Expiry and feature
  caps are still enforced.
</Note>

### Validating your license

You can manually validate a license at any time using the license utility:

```bash theme={null}
/opt/wirekite/license/license -cmd validate \
  -input /opt/wirekite/license/wirekite.license \
  -keyfile /opt/wirekite/license/wirekite.key
```

This outputs the license details including customer name, expiration date,
days remaining, features, and any validation errors.

### Checking licensed features

To list all features in your license:

```bash theme={null}
/opt/wirekite/license/license -cmd features \
  -input /opt/wirekite/license/wirekite.license \
  -keyfile /opt/wirekite/license/wirekite.key
```

To check for a specific feature:

```bash theme={null}
/opt/wirekite/license/license -cmd features \
  -input /opt/wirekite/license/wirekite.license \
  -keyfile /opt/wirekite/license/wirekite.key \
  -check-feature prod
```

### Usage caps

Some licenses include usage caps that limit the total bytes processed for
data migrations and CDC replication. When a cap is reached, the affected
loader exits with code 2 and the orchestrator reports the limit in its log.

Usage is tracked in `/opt/wirekite/instance/usage.log`. You can view current
usage through the [Web Interface](/run/execution/ux) under the license section.

<Note>
  A usage cap of `0` means unlimited. If your license does not include usage
  caps, there are no byte limits on data migration or CDC replication.
</Note>

### Replacing a license

To replace an expired or updated license:

* **On-Prem.** Re-run the installer with the new license pair:
  ```bash theme={null}
  sudo ./wirekite-installer.run -- \
      --license-file=/path/to/new-wirekite.license \
      --license-key=/path/to/new-wirekite.key
  ```
* **Docker.** Replace both files in your `--license-pair-dir`, then
  `docker restart wirekite-<your-id>`. The container picks up the new pair
  from the bind-mount on next license validation.
* **Cloud.** Send the new license to your Wirekite rep; we install it on
  your VM.

Running migrations do not need to be restarted — the new license takes effect
the next time validation is performed.