> For the complete documentation index, see [llms.txt](https://wiki.inels.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.inels.com/inels-harmony/getting-started/installing-harmony-on-a-server.md).

# Installing Harmony on a server

What the server needs, registering the project, running the installer, and the five-gateway trial.

{% hint style="info" %}
**Who this page is for:** the person putting Harmony on a server for the first time — an integrator, installer, or the hotel's IT contact.

If Harmony is already running and you just need to log in, go to [Signing in](/inels-harmony/getting-started/signing-in.md).
{% endhint %}

The whole job is four things: prepare a server, register the project in Harmony Portal to get a token, run one command on the server, then activate a licence if the hotel needs more than five gateways.

## 1 · What the server needs

Harmony runs as four Docker containers — MariaDB, Mosquitto, the application, and nginx — on one Linux machine inside the hotel.

| Requirement          | Detail                                                                                                                                          |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Operating system** | Ubuntu 22.04 or later, or Debian 12 or later. The installer refuses anything else.                                                              |
| **Architecture**     | `x86_64` or `aarch64` / `arm64`                                                                                                                 |
| **Free disk**        | **At least 3 GB free on `/opt`.** The installer stops if there is less.                                                                         |
| **Memory**           | Not enforced by the installer, but four containers plus a database want headroom — size the machine with a couple of gigabytes of RAM to spare. |
| **Docker**           | Docker Engine plus the Compose plugin. **If Docker is missing the installer adds Docker's repository and installs it for you.**                 |
| **Access**           | root, or a user with `sudo`                                                                                                                     |
| **Internet**         | Needed to download the release, register with the portal and activate a licence. Not needed afterwards for day-to-day running.                  |
| **IP address**       | **Must be fixed.** Set it statically or reserve it on the router.                                                                               |

{% hint style="warning" %}
**A fixed IP address is not optional.** Every gateway, every front-desk browser and every housekeeping phone points at this address. If a DHCP lease moves the server, the whole hotel loses Harmony at once.
{% endhint %}

A small rack server, a mini-PC or a modest VM is plenty. Harmony is not a demanding application — it is the *availability* that matters, so put it on wired power and wired network if you can.

#### Ports it will use

| Port | Serves         |
| ---- | -------------- |
| 80   | Landing page   |
| 81   | Administration |
| 82   | Reception      |
| 83   | Housekeeping   |

Ports 80, 81 and 82 can be changed at install time with `--landing-port`, `--admin-port` and `--reception-port` if something already uses them. The installer also applies a LAN firewall rule set so the apps are reachable from the hotel network and not beyond it.

## 2 · Register the project in Harmony Portal

Do this **before** you run the installer, so you have the token ready.

{% stepper %}
{% step %}

#### Open Harmony Portal

Go to [harmony-portal.inels.com](https://harmony-portal.inels.com) and sign in with your partner account.
{% endstep %}

{% step %}

#### Create the project for this property

Enter the hotel's details as the project. This is what the server will report against, so use the name the hotel actually trades under.
{% endstep %}

{% step %}

#### Copy the registration token

The portal issues a token that starts with `hrt_`. Copy it somewhere you can paste from on the server — it is needed in the next step.
{% endstep %}
{% endstepper %}

{% hint style="info" %}
**What registration actually does.** During install the server sends the portal its hotel name, Harmony version, IP address, operating system, Docker version and port numbers. The portal returns an API key, stored on the server at `/opt/hrs-container/.harmony/portal.json`. From then on the server sends a periodic heartbeat, which is how the portal knows the installation is alive and which version it runs.

No guest data is sent to the portal.
{% endhint %}

{% hint style="success" %}
**Forgot the token, or installed without one?** Registration is optional at install time and can be done afterwards:

```bash
sudo /opt/hrs-container/portal-agent/register-portal.sh \
  --registration-token hrt_xxxxxxxxxxxx
```

{% endhint %}

## 3 · Run the installer on the server

SSH into the server and run one command.

{% tabs %}
{% tab title="Normal install (online)" %}

```bash
curl -sL https://raw.githubusercontent.com/elkoep-dev/harmony-releases/main/install.sh \
  | sudo bash -s -- \
    --version 1.0.11 \
    --registration-token hrt_xxxxxxxxxxxx \
    --hotel-name "Grand Palace Hotel" \
    --password "YourSecureDbPassword"
```

Replace the token with the one from the portal, and the hotel name with the property's real name.
{% endtab %}

{% tab title="Offline install (tarball)" %}
For a server with no internet access, copy the release tarball across first, then:

```bash
sudo mkdir -p /opt/hrs-container
sudo tar xzf /tmp/harmony-1.0.11.tar.gz -C /opt/hrs-container --strip-components=1
cd /opt/hrs-container
sudo ./install.sh \
  --hotel-name "Grand Palace Hotel" \
  --password "YourSecureDbPassword" \
  --skip-portal
```

Register with the portal later, once the machine has a connection, using `register-portal.sh` as shown above.
{% endtab %}
{% endtabs %}

#### The options you are most likely to need

| Option                                               | Does                                                               |
| ---------------------------------------------------- | ------------------------------------------------------------------ |
| `--version`                                          | Which Harmony release to install                                   |
| `--registration-token`                               | The `hrt_…` token from Harmony Portal                              |
| `--hotel-name`                                       | The property name, used in the app and reported to the portal      |
| `--password`                                         | The database password. Leave it out and the installer prompts you. |
| `--skip-portal`                                      | Install without registering                                        |
| `--landing-port`, `--admin-port`, `--reception-port` | Use different ports                                                |
| `--non-interactive`                                  | No prompts — for scripted installs                                 |
| `--tarball`                                          | Install from a local file instead of downloading                   |

## 4 · Check the install worked

```bash
sudo /opt/hrs-container/scripts/verify-install.sh
```

Every check should report OK. Then open `http://<server-ip>:81` in a browser and confirm the sign-in page appears.

If anything went wrong, the full install log is at `/var/log/harmony-install.log`.

## 5 · First sign-in

The installer creates one account:

| Field    | Value               |
| -------- | ------------------- |
| Email    | `admin@hotel.local` |
| Password | `harmony`           |

{% hint style="danger" %}
**Change this password immediately.** It is identical on every Harmony installation in the world. [Signing in](/inels-harmony/getting-started/signing-in.md) shows you how, and it takes about a minute.
{% endhint %}

## 6 · Licensing: the first five gateways are free

A fresh installation runs on a **trial licence that allows five gateways**. There is no time limit on it — if the property needs five gateways or fewer, there is nothing more to do and nothing to buy.

#### When you need more than five

Harmony counts gateways as you add them. When you try to add a sixth, it refuses and tells you the current limit.

{% hint style="success" %}
**Nothing breaks when you hit the limit.** Harmony simply will not accept another gateway. Everything already configured keeps working, and the moment a licence is applied you can carry on where you left off.
{% endhint %}

#### Getting a licence

{% stepper %}
{% step %}

#### Count the gateways this property needs

Count *gateways*, not rooms — one BUS unit may serve many rooms, so the gateway count is what the licence is sized against.
{% endstep %}

{% step %}

#### Request the licence from ElkoEP

Send the request through your usual iNELS partner or support contact, quoting the property and the number of gateways required. ElkoEP issues the licence.
{% endstep %}

{% step %}

#### Receive the licence key

It arrives in the form `HRM-XXXX-XXXX-XXXX-XXXX`.
{% endstep %}

{% step %}

#### Apply it in Administration

Open **Licensing**, paste the key into **Harmony license key**, and click **Apply license**. The new gateway and room allowances take effect straight away.

Full detail in [Step 3 · Licence and Harmony Cloud](/inels-harmony/administration/step-3-licence-and-harmony-cloud.md).
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
**The server needs outbound internet to activate a licence.** Activation is verified through Harmony Cloud. It is needed for that moment only — the hotel runs perfectly well offline afterwards.
{% endhint %}

## If the install fails

<details>

<summary>"Unsupported operating system"</summary>

The installer only supports Ubuntu and Debian. Other distributions are not supported, even where Docker runs fine on them.

</details>

<details>

<summary>"Insufficient disk space"</summary>

There is less than 3 GB free on `/opt`. Free some space or grow the volume, then run the installer again — it is safe to re-run.

</details>

<details>

<summary>A port is already in use</summary>

Something else on the machine holds port 80, 81 or 82 — very often an existing web server. Either stop it, or install Harmony on different ports with `--landing-port`, `--admin-port` and `--reception-port`.

</details>

<details>

<summary>"Could not reach the portal"</summary>

Harmony is installed and running; only registration failed. Check the server's internet access, then register separately with `register-portal.sh`. Nothing needs reinstalling.

</details>

<details>

<summary>Something else</summary>

Read `/var/log/harmony-install.log` — the installer writes every step there, and the first error in the file is usually the real one.

</details>

## What to do next

With the server up and the admin password changed, the hotel itself still has to be configured — floors, rooms, gateways, devices and the rest. That is the [Administration](/inels-harmony/administration.md) section, and it starts with [Before you start](/inels-harmony/administration/before-you-start.md).