How to deploy iociane
Last updated: 2025-09-20

`iocaine` is a single binary, and apart from an optional configuration file, a wordlist, and some sources for its markov generator, and an optional but highly recommended request handler script there’s nothing else it needs. It has no persistent state, no database, and writes nothing to disk - unless metrics persistence is enabled. Nevertheless, it is a good idea to run it as its dedicated user, and never expose it to the open Internet - always run it behind a reverse proxy. Always run it behind a reverse proxy, because in the recommended mode of operation, when `iocaine` decides the fate of every request that comes its way, it is the task of the reverse proxy to serve the real content when `iocaine` tells it to. See the HOWTO section for examples about how to deploy various reverse proxies in front of `iocaine`.

Below, you will find examples for deploying with `systemd`, without it, with `docker`, and on NixOS, using the module nixocaine provides. Keep in mind, this is just the `iocaine` part of deployment. How you deploy the reuqest handler, and the reverse proxy, is not covered here.

# Compiling `iocaine`

Automatically built binaries are available for `x86-64` and `aarch64` Linux platforms (statically built against musl libc) . To download it, you can use a command like the following:

    curl -s https://git.madhouse-project.org/api/packages/iocaine/generic/iocaine-binaries/2.5.1/iocaine-2.5.1.x86_64-linux.zst | \
      unzstd - -o /usr/local/bin/iocaine && chmod +x /usr/local/bin/iocaine

Or for `aarch64`:

    curl -s https://git.madhouse-project.org/api/packages/iocaine/generic/iocaine-binaries/2.5.1/iocaine-2.5.1.aarch64-multiplatform.zst | \
      unzstd - -o /usr/local/bin/iocaine && chmod +x /usr/local/bin/iocaine

If you wish to compile it yourself, `iocaine` is written in Rust, compiling it is just a `cargo install iocaine` (which will install the latest stable release), or `cargo install --path .` away, assuming you have Rust installed. See their getting started guide to get there.

# Deploying with `systemd`

See `data/iocaine.service` for a systemd service template. To use it, install `iocaine` somewhere, and copy the service file to `/etc/systemd/system/`, and edit it so it references the binary you installed, and the configuration file you prepared.

When done editing, you can `systemctl daemon-reload` (as root, of course), followed by `systemctl start iocaine`. If everything went well, you’re done.

The provided systemd service tries to restrict the tool as much as possible, and uses `DynamicUser=true`, meaning that no user will need to be created, systemd will take care of it.

# Deploying without `systemd`

To deploy without systemd, the easiest path is to create a dedicated user:

    useradd -m iocaine

Then, place the `iocaine` binary and the configuration you prepared into this user’s `$HOME`:

    mkdir -p $HOME/iocaine
    cp iocaine config.toml $HOME/iocaine/

Then, you can run it like this:

    su -l -u iocaine /home/iocaine/iocaine/iocaine \
       --config-file /home/iocaine/iocaine/config.toml

# Deploying via Docker

There’s an automatically built container image, for those who may wish to try - or deploy - `iocaine` via Docker (for `linux/amd64` and `linux/arm64` platforms). The best way to use it, is likely via `docker compose`. An example of that is provided in `data/compose.yaml`.

To use it, place the word list and the training text in `data/container-volume`, and then you can simply start things up like this:

    docker compose up -d

Voila!

If you wish to change the configuration, you can either do so via environment variables, or you can remove those from the compose file, and supply your own, TOML-based configuration file, as shown in `data/compose-toml.yaml`.

If you enable metrics, be aware that those are exposed on a different port. Don’t forget to add that to the `ports` section of `compose.yaml`!

# Deploying on NixOS

Deploying under NixOS is made simple by using the nixosModule provided by nixocaine. It takes care of setting up the `systemd` service, sufficiently hardened, so all that is required of you is to enable the service, please read the NixOS HOWTO for details.

The module supports setting up multiple servers: each submodule under `services.iocaine.servers` will be a different instance of `iocaine`. The module also adds an overlay, making the `iocaine-stable` (the latest stable release) or `iocaine-unstable` (head of the main development branch) packages available, depending on which branch of `nixocaine` is in use. The `services.iocaine.package` attribute can be used to set a custom package.