iocaine/docs/content/deploying/iocaine.md

---
title: Deploying iocaine
description: Deploying iocaine
---

How to deploy `iocaine` highly depends on what kind of system you're using. Below, you will find examples for deploying with `systemd`, without it, with `docker`, and on NixOS, using the module this repository's flake provides. This section deals with deployment, configuration is documented [elsewhere](@/configuration/index.md), and so is configuring the reverse proxy ([nginx](@/deploying/nginx.md) or [Caddy](@/deploying/caddy.md)).

# Compiling `iocaine`

Automatically built binaries are available for x86-64 Linux platforms (statically built against musl libc) [here](https://git.madhouse-project.org/algernon/-/packages/generic/iocaine/0.1.0-snapshot). To download it, you can use a command like the following:

```sh
curl -s https://git.madhouse-project.org/api/packages/algernon/generic/iocaine/0.1.0-snapshot/iocaine.zst | \
  unzstd - -o /usr/local/bin/iocaine && chmod +x /usr/local/bin/iocaine
```

But if you wish to compile it yourself, `iocaine` is written in [Rust](https://www.rust-lang.org/), compiling it is just a `cargo build -r` away, assuming you have Rust installed. See their [getting started](https://www.rust-lang.org/learn/get-started) guide to get there. Once compiled, the binary will be located in `target/release/iocaine`, you can copy it wherever it is convenient for you.

# Deploying with `systemd`

See <code>[data/iocaine.service](https://git.madhouse-project.org/algernon/iocaine/src/branch/main/data/iocaine.service)</code> 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:

```sh
useradd -m iocaine
```

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

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

Then, you can run it like this:

```sh
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. The best way to use it, is likely via `docker compose`. An example of that is provided in <code>[data/compose.yaml](https://git.madhouse-project.org/algernon/iocaine/src/branch/main/data/compose.yaml)</code>.

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:

```sh
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 <code>[data/compose-toml.yaml](https://git.madhouse-project.org/algernon/iocaine/src/branch/main/data/compose-toml.yaml)</code>.

# Deploying on NixOS

Deploying under NixOS is made simple by using the nixosModule provided by this repository's flake. It takes care of setting up the `systemd` service, sufficiently hardened, so all that is required of you is to enable the service, and configure the sources.

```nix
{
  inputs = {
    nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
    iocaine = {
      url = "git+https://git.madhouse-project.org/algernon/iocaine.git";
      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs = { ... }@inputs: {
    nixosConfigurations = {
      your-hostname = inputs.nixpkgs.lib.nixosSystem {
        inherit inputs;
      };
      modules = [
        inputs.iocaine.nixosModules.default
        (
          {
            inputs,
            lib,
            config,
            pkgs,
            ...
          }:
          {
            services.iocaine = {
              enable = true;
              config = {
                sources = {
                  words = "${pkgs.scowl}/share/dict/wamerican.txt";
                  markov = [
                    "/some/path/to/a/training-document.txt"
                  ];
                };
              };
            };
          }
        )
      ];
    };
  };
}
```

</details>