iocaine/docs/content/deploying/iocaine.md

title	description
Deploying iocaine	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, and so is configuring the reverse proxy (nginx or Caddy).

Compiling iocaine

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

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, compiling it is just a cargo build -r away, assuming you have Rust installed. See their getting 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 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. 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.

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.

{
  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"
                  ];
                };
              };
            };
          }
        )
      ];
    };
  };
}