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).

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!

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