> ## 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.

# On-Prem Installation

> Install Wirekite on your own Linux host using the self-extracting installer.

The on-prem path delivers Wirekite as a single self-extracting installer
(`wirekite-installer.run`) that you run on a Linux host you control. Wirekite
lives at `/opt/wirekite/`, the web UI runs as a systemd service on port `8443`,
and all configuration lives in `/etc/wirekite/wirekite.cfg`.

## Requirements

| Requirement      | Notes                                                                                |
| ---------------- | ------------------------------------------------------------------------------------ |
| Operating system | Ubuntu 20.04+, RHEL 8+, Debian 11+, or Amazon Linux 2                                |
| Architecture     | x86\_64                                                                              |
| Privileges       | Root or `sudo`                                                                       |
| Init system      | systemd                                                                              |
| Free TCP ports   | `8443` (UX) and `9443` (API, only if API enabled)                                    |
| Disk             | \~2 GB for the install tree; migration data + change files are on disks you allocate |

<Note>
  If you plan to use **Oracle as a source**, the installer bundles the runtime
  libraries it needs — no separate Oracle Instant Client install is required.
</Note>

## What you receive from Wirekite

Two artifacts, delivered out-of-band (signed URL, secure email, or portal):

1. **`wirekite-installer.run`** — the self-extracting installer. Same binary
   regardless of which source/target you'll use.
2. **License pair** — two small files:
   * `wirekite.license` — your customer license
   * `wirekite.key` — the decryption key paired with that license

Keep both license files together. The installer expects them as a pair.

## Install

### Step 1: Run the installer

Non-interactive (recommended for scripting):

```bash theme={null}
sudo ./wirekite-installer.run -- \
    --license-file=/path/to/wirekite.license \
    --license-key=/path/to/wirekite.key
```

The `--` separates installer-extractor arguments from the install-script
arguments that follow.

The installer will:

1. Extract the install tree to `/opt/wirekite/`
2. Create the `wirekite` system user
3. Validate and install your license pair to `/opt/wirekite/license/`
4. Write `/etc/wirekite/wirekite.cfg` with `DEPLOYMENT=onprem`
5. Mint a self-signed CA and TLS server cert (`wirekite_ca` mode, default)
6. Generate the per-host `instance/encryption.key`
7. Install the dynamic linker config for bundled database drivers
8. Install the `wirekite-ux.service` systemd unit and start it

If you omit `--license-file` / `--license-key`, the installer prompts for them
interactively.

### Step 2: Browse to the UI

Open `https://<host>:8443/` in a browser. Because the default cert is
self-signed, your browser will show a "your connection is not private"
warning — accept it (or see [Bring your own TLS
certificate](#bring-your-own-tls-certificate) below).

You'll land on the **setup page**. Create the **root user** (username +
password). After that, sign in and start configuring sources, targets, and
migrations.

## Bring your own TLS certificate

To avoid the browser warning, supply a CA-issued certificate at install time:

```bash theme={null}
sudo ./wirekite-installer.run -- \
    --license-file=/path/to/wirekite.license \
    --license-key=/path/to/wirekite.key \
    --cert-mode=customer \
    --cert-file=/path/to/server.crt \
    --key-file=/path/to/server.key
```

The certificate's `CN` or SAN must match the hostname users will type in the
browser.

## Split-disk layout (recommended for production)

Wirekite reads two optional keys from `/etc/wirekite/wirekite.cfg`:

```ini theme={null}
DATA_BASE_DIR=/mnt/data
CHANGE_BASE_DIR=/mnt/change
```

* `DATA_BASE_DIR` — where extracted-row files for initial loads are staged
* `CHANGE_BASE_DIR` — where CDC change files are staged

Putting these on separate physical disks improves throughput and isolates
data-phase IO from CDC-phase IO. After editing the cfg, restart the UX server:

```bash theme={null}
sudo systemctl restart wirekite-ux
```

Both directories must be writable by the `wirekite` user:

```bash theme={null}
sudo chown wirekite:wirekite /mnt/data /mnt/change
```

If these keys are unset, Wirekite falls back to per-migration subdirectories
under `$WIREKITE_HOME/instance/<migration>/`.

## Service management

The installer registers `wirekite-ux.service`. Manage it with the usual
`systemctl` commands:

```bash theme={null}
sudo systemctl status wirekite-ux
sudo systemctl restart wirekite-ux
sudo journalctl -u wirekite-ux -f
```

`wirekite-ux` is the only unit required. The orchestrator and per-database
loaders are launched as child processes by the UX server when migrations run.

## Upgrade

To upgrade to a new release:

1. Stop the UX server:
   ```bash theme={null}
   sudo systemctl stop wirekite-ux
   ```

2. Run the new installer:
   ```bash theme={null}
   sudo ./wirekite-installer.run -- \
       --license-file=/path/to/wirekite.license \
       --license-key=/path/to/wirekite.key
   ```

The installer preserves your existing state:

* `/opt/wirekite/instance/` — encryption key, users, migrations metadata
* `/opt/wirekite/license/` — your license pair
* `/opt/wirekite/certs/` — your TLS certs

3. The installer restarts the UX server on success.

## Uninstall

```bash theme={null}
sudo /opt/wirekite/packager/uninstall.sh
```

Add `-y` to skip the confirmation prompt. The uninstaller stops + removes the
systemd unit, deletes `/opt/wirekite/`, removes the `wirekite` user, and
deletes `/etc/wirekite/`.

<Warning>
  Uninstalling removes all migration configurations and data under
  `/opt/wirekite/instance/`. Back it up first if you need to preserve
  your migrations.
</Warning>

## Troubleshooting

### License validation failed

Run the license utility directly:

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

Common failures:

* `License has expired` — contact your Wirekite rep for a renewal.
* `Host ID mismatch` — your license is bound to a specific MAC address.
  Either run on the bound host or request a host-independent license.
* `license file has been tampered with` — the `.license` and `.key` are
  mismatched, or one was modified after issue. Reinstall the pair you
  originally received.

### UX server won't start

```bash theme={null}
sudo journalctl -u wirekite-ux -n 100
sudo tail -f /opt/wirekite/ux/logs/ux-server.log
```

Most startup failures are license, port, or cert issues. Check that port
`8443` is free (`sudo lsof -i :8443`) and that
`/opt/wirekite/ux/server/certs/` contains a readable `server.crt` +
`server.key`.