# Install HotKV

> Install HotKV On-Premise from the Linux packages or the Docker image, check that it runs, and find its files and ports.

URL: https://docs.hotkv.com/get-started/install/


This page covers installing the HotKV server on your own machines. If you
want a managed instance instead, use [HotKV Cloud](https://docs.hotkv.com/quickstart-cloud/index.md):
there is nothing to install. For the configuration file and installing a
license, continue with [Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md)
once the server runs.

The HotKV server is not offered as a public download, and it is not published in
public package repositories or container registries. HotKV On-Premise is
supplied to Enterprise customers: when you buy a license, your account team
sends you a private download link for the packages and the Docker image.
[Contact sales@hotkv.com](mailto:sales@hotkv.com?subject=HotKV%20On-Premise%20inquiry)
to talk about On-Premise. [HotKV Cloud](https://docs.hotkv.com/quickstart-cloud/index.md) needs no
download at all.

## What you get

| Format | Platforms | File name |
| --- | --- | --- |
| Debian package | Debian, Ubuntu and derivatives; x86_64 (`amd64`) and ARM64 (`arm64`) | `hotkv-enterprise_<version>_<arch>.deb` |
| RPM package | RHEL, Rocky Linux, Fedora and derivatives; `x86_64` and `aarch64` | `hotkv-enterprise-<version>-1.<arch>.rpm` |
| Docker image | Linux containers | see [Docker and Kubernetes](https://docs.hotkv.com/operate/docker-and-kubernetes/index.md) |

The packages need systemd. Every package contains:

- `hotkv`, the server, and `hotkv-cli`, the command-line client
  ([hotkv-cli](https://docs.hotkv.com/get-started/hotkv-cli/index.md));
- `hotkv-migrate-elasticache`, `hotkv-migrate-azure-cache` and
  `hotkv-migrate-memorystore`, tools that copy keys from a running
  Redis-compatible server (see
  [Migrate from Redis](https://docs.hotkv.com/get-started/migrate-from-redis/index.md#copy-keys-from-a-running-server));
- a systemd service, `hotkv`, that runs the server as its own `hotkv` user;
- a commented configuration file and man pages (`man hotkv`, `man hotkv-cli`).

## Install a package

Download the package for your platform from the private link your account
team sent you, then install it from the directory you saved it in:

```bash
# Debian / Ubuntu
sudo apt install ./hotkv-enterprise_*.deb

# RHEL / Rocky / Fedora
sudo dnf install ./hotkv-enterprise-*.rpm
```

Installing creates the `hotkv` user and group and the data and log
directories. It does not start the server: enable and start the service
yourself.

```bash
sudo systemctl enable --now hotkv
```

## Check the installation

```bash
hotkv --version
# HotKV v<version>

systemctl status hotkv

hotkv-cli PING
# PONG
```

`INFO server` reports the running version as `hotkv_version`. The server
also reports `redis_version:8.4.0` (the `compat-redis-version` setting): that is the Redis version whose
commands HotKV follows, which client libraries use to pick the commands
they send.

```bash
hotkv-cli INFO server | grep -E 'hotkv_version|redis_version'
```

The server logs to standard output by default, which systemd keeps in the
journal:

```bash
journalctl -u hotkv -f
```

## The systemd service

The `hotkv` service starts `/usr/bin/hotkv --config /etc/hotkv/hotkv.conf`
as the `hotkv` user, with `/var/lib/hotkv` as its working directory. Points
worth knowing:

- **Ready means ready.** The service counts as started once the data is
  loaded and the server accepts connections, so units ordered after it
  find it serving.
- **No start or stop time limit.** Loading or saving a large data set can
  take a while; systemd waits for it. Stopping the service (SIGTERM) saves
  a snapshot first when save points are configured, and with the AOF on
  every write is already in it.
- **Restarted on failure.** The service restarts the server 5 seconds
  after it exits unexpectedly.
- **Open files.** The service allows 65535 open files, which bounds how
  many clients can connect at once together with `maxclients`.
- **Read-only system.** The server can write only to `/var/lib/hotkv`,
  `/var/log/hotkv` and `/run/hotkv`. Keep files the server writes there:
  an `aclfile` that `ACL SAVE` writes, a `logfile`, or a different `dir`.
  `CONFIG REWRITE` cannot update `/etc/hotkv/hotkv.conf` under this
  service; edit the file instead.

To change how the service starts, for example to run with
`/etc/hotkv/hotkv.toml`, use `sudo systemctl edit hotkv`; see
[Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md#2-configuration-file-basics).

## File locations

| Path | What it is |
| --- | --- |
| `/usr/bin/hotkv`, `/usr/bin/hotkv-cli` | The server and the client |
| `/etc/hotkv/hotkv.conf` | The configuration the service loads (kept on upgrades) |
| `/etc/hotkv/hotkv.toml.example` | The same settings in TOML form |
| `/var/lib/hotkv` | Data: snapshots (`dump.hkv`) and the AOF (`appendonly.hkv`) |
| `/var/log/hotkv` | Log files, when `logfile` points there (rotated weekly by `/etc/logrotate.d/hotkv`) |
| `/run/hotkv` | Runtime files |
| `/lib/systemd/system/hotkv.service` | The systemd unit |

`/etc/hotkv/hotkv.conf` is readable by `root` and the `hotkv` group only,
since it can hold passwords. Put your license file in `/etc/hotkv` too, for
example `/etc/hotkv/hotkv.license`.

> **Caution**
> Removing the package keeps your data and configuration. Purging it
> (`apt purge`) deletes `/etc/hotkv`, `/var/lib/hotkv` and `/var/log/hotkv`,
> including your license file and all data. Copy anything you want to keep
> first.

## Ports

| Port | Used for | Default |
| --- | --- | --- |
| `port` | Client connections (RESP) | `6379` |
| `tls-port` | TLS client connections | off; see [TLS](https://docs.hotkv.com/operate/tls/index.md) |
| `cluster-port` | Cluster bus, in cluster mode | client port + 10000 |
| Replication port | Only with `replication.dedicated-port yes`: replicas connecting to their primary there. Without it, replicas connect to the primary's client port. | `6389` outside cluster mode (`replication.port`); client port + 20000 in cluster mode |
| `metrics-port` | Prometheus metrics over HTTP | off (`0`) |

The packaged configuration listens on `127.0.0.1` only. To accept clients
from other hosts, set `bind` and a password; with no password, protected
mode refuses clients from other hosts (see
[Security](https://docs.hotkv.com/security/index.md#protected-mode)). Open only the ports you use in
your firewall, and keep the cluster bus port (and the replication port, if
you use one) reachable from the other nodes only. A cluster node needs only
its client port and its bus port; see
[Deploy on VMs and cloud](https://docs.hotkv.com/clustering/production/index.md#ports-and-firewalls).

## Docker

The HotKV Docker image runs the same server with the same configuration
file, listening on every interface with its data in a `/data` volume.
See [Docker and Kubernetes](https://docs.hotkv.com/operate/docker-and-kubernetes/index.md).

## Next steps

- [Quick start: On-Premise](https://docs.hotkv.com/quickstart-onpremise/index.md): the configuration file
  and installing your license.
- [hotkv-cli](https://docs.hotkv.com/get-started/hotkv-cli/index.md): the command-line client.
- [Security](https://docs.hotkv.com/security/index.md): passwords, TLS and protected mode before you open
  the server to the network.
- [Upgrading](https://docs.hotkv.com/operate/upgrading/index.md): moving to a newer version.