Installing Harmony on a server

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

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.

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.

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.

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.

1

Open Harmony Portal

Go to harmony-portal.inels.com and sign in with your partner account.

2

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.

3

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.

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.

Forgot the token, or installed without one? Registration is optional at install time and can be done afterwards:

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

3 · Run the installer on the server

SSH into the server and run one command.

Normal install (online)

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.

Offline install (tarball)

For a server with no internet access, copy the release tarball across first, then:

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.

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

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	[e-mail]
Password	harmony

Change this password immediately. It is identical on every Harmony installation in the world. Signing in shows you how, and it takes about a minute.

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.

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.

Getting a licence

1

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.

2

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.

3

Receive the licence key

It arrives in the form HRM-XXXX-XXXX-XXXX-XXXX.

4

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.

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.

If the install fails

"Unsupported operating system"

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

"Insufficient disk space"

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.

A port is already in use

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.

"Could not reach the portal"

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

Something else

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

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 section, and it starts with Before you start.