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.