Skip to main content
Version: 3.4.0

Server Setup

Now that the Hotrod executable is installed and available on the system, we'll set up Hotrod Server. This involves:

  1. Creating a system user and group.
  2. Creating a data directory.
  3. Creating a systemd unit file to manage the process.
  4. Start Hotrod Server.

At the end of this section, You should have Hotrod Server's front-end accessible via your browser.

Create a system user and group​

Create a system user and group for hotrod:

adduser --system --home /home/hotrod --disabled-login --group hotrod
Warning

Do not run Hotrod Server with root privileges.

Create a data directory​

Hotrod Server requires a data directory to store internal data, pipes, logs and metric data.

Create a data directory with appropriate ownership:

mkdir /var/lib/hotrod
chown -R hotrod:hotrod /var/lib/hotrod

Setup systemd service​

Create a systemd unit file:

vi /etc/systemd/system/hotrod-server.service

Hotrod Server is configured through either command line flags or environment variables. We'll be using the latter.

At minimum, Hotrod Server needs to know:

  1. Where to store it's data (HOTROD_STAGING_DIR)
  2. What network address to bind to for it's HTTP API and frontend (HOTROD_BIND_ADDRESS)
tip

See hotrod run server --help for startup options and their environment variable equivalents.

We'll specify the server's configuration in the unit file, as follows:

[Unit]
Description=hotrod-server

[Install]
WantedBy=multi-user.target

[Service]
User=hotrod
Group=hotrod
ExecStart=hotrod run stand-alone
Restart=on-failure

########################### configuration

Environment=HOTROD_STAGING_DIR=/var/lib/hotrod
Environment=HOTROD_BIND_ADDRESS=127.0.0.1:3000
Environment=HOTROD_LOG_RETENTION_DAYS=30
Environment=HOTROD_LICENSE_EULA_ACCEPT=yes
Environment=HOTROD_ADMIN_INIT_PASSWORD=changeMeVerySoon

Firstly, using hotrod run stand-alone will start the server with an internal agent.

If you would like to start Hotrod server with an internal agent - which is useful for testing - modify the start command:

-ExecStart=hotrod run stand-alone
+ExecStart=hotrod run server

We've added three additional environment variables:

  • HOTROD_LOG_RETENTION_DAYS determines how long Hotrod Server retains logs and metrics data. We'll use the default value of 30 days.
  • HOTROD_LICENSE_EULA_ACCEPT=yes prevents the one-time prompt for accepting Hotrod's End User License Agreement.
  • HOTROD_ADMIN_INIT_PASSWORD provides an initial password for Hotrod Server's admin user.

When HOTROD_ADMIN_INIT_PASSWORD is not present when Hotrod Server initializes it's user database for the first time, a random password will be generated and printed in the process's STDOUT output.

Note

Whether using the HOTROD_ADMIN_INIT_PASSWORD environment variable, or relying on the generated password on first startup, it is recommended to change the password at your earliest convenience.

Note

Besides the configured staging directory, the Hotrod Server process will persist some minimal state information to the home directory of the user that the process runs as (~/.local/share/hotrod*/). This directory should be accessible and writable by the Hotrod Server process.

Once you have saved the unit file, reload systemd's unit definitions:

systemctl daemon-reload

To start Hotrod server at system boot, we enable the service with:

systemctl enable hotrod-server

Finally, start Hotrod Server:

systemctl start hotrod-server

And verify that it started started successfully:

systemctl status hotrod-server

It's a good idea to inspect the startup output, which will contain the admin user's password if it wasn't set with HOTROD_ADMIN_INIT_PASSWORD:

journalctl -u hotrod-server

If there were no startup issues, Hotrod Server should now be serving it's user interface and API on the configured address and port (specified with HOTROD_BIND_ADDRESS).

Head to http://localhost:3000 in a browser. You can log in with username admin, and the password provided or received.

tip

Hotrod server can be configured to use TLS, by providing a certificate and key file to the hotrod server run command. See hotrod server run --help for details.

When using a reverse proxy for TLS termination, like caddy or nginx, it's recommended to configure the appropriate HTTP client address headers, for logging purposes.