rustfs/deploy/build/rustfs.nixos.md

RustFS NixOS Service Guide

This guide explains how to use rustfs.nixos.service.nix as a starting point for managing RustFS with systemd on NixOS.

1. What the example does

The NixOS example is designed for the current RustFS startup model:

• Type = "notify" so systemd waits for RustFS to publish READY=1
• a dedicated rustfs system user instead of running the service as root
• WorkingDirectory = "/var/lib/rustfs" instead of using a log directory as the working directory
• KillMode = "control-group" and SendSIGKILL = true so stuck shutdowns do not leave the unit hanging forever
• StandardOutput = "journal" and StandardError = "journal" so logs stay in journald
• runtime configuration through RUSTFS_* environment variables
• secret file wiring through RUSTFS_ACCESS_KEY_FILE and RUSTFS_SECRET_KEY_FILE

2. Import the example into your NixOS configuration

You can either copy the contents into your own module, or import it directly and provide rustfsPkg.

Example:

{
  imports = [
    ./deploy/build/rustfs.nixos.service.nix
  ];

  _module.args.rustfsPkg = pkgs.callPackage ./path/to/rustfs/package.nix { };
}

If you already package RustFS through a flake output or overlay, point rustfsPkg at that package instead.

3. Adjust the default paths

The example uses these defaults:

• data directory: /srv/rustfs
• state directory: /var/lib/rustfs
• log directory: /var/log/rustfs

Before enabling the service, make sure your RustFS volumes and any TLS material match your real deployment layout.

The example currently sets:

RUSTFS_VOLUMES = "/srv/rustfs/vol{1...4}";
RUSTFS_ADDRESS = "0.0.0.0:9000";
RUSTFS_CONSOLE_ENABLE = "true";
RUSTFS_CONSOLE_ADDRESS = "0.0.0.0:9001";

Update these values to match your storage topology and exposure policy.

4. Wire secrets through runtime files

Do not put credentials directly into environment if they would be stored in the Nix store.

RustFS supports file-based secrets, so on NixOS the preferred pattern is:

systemd.services.rustfs.environment = {
  RUSTFS_ACCESS_KEY_FILE = config.age.secrets.rustfs-access.path;
  RUSTFS_SECRET_KEY_FILE = config.age.secrets.rustfs-secret.path;
};

The same shape also works with sops-nix, agenix, or any other runtime secret manager that exposes files under /run.

5. Rebuild and enable the service

After integrating the unit into your NixOS configuration:

sudo nixos-rebuild switch
sudo systemctl enable --now rustfs

6. Verify readiness and logs

Check whether systemd sees the service as fully ready:

systemctl status rustfs
systemctl show rustfs -p Type -p ActiveState -p SubState

Follow the service logs:

journalctl -u rustfs -f

Look for the point where RustFS reports that startup is complete and systemd transitions the unit into the running state.

7. Common NixOS-specific notes

• If you previously used SendSIGKILL = false, expect shutdown behavior to change. The example favors reliable service recovery over indefinite graceful waits.
• If your service really needs more startup time, increase TimeoutStartSec, but keep it bounded. Very large values can hide broken startup states.
• If you must write file logs instead of journald logs, change StandardOutput and StandardError, then make sure the target path is writable by the rustfs user.
• If you decide to run as root, review the hardening flags again. The example is written for a dedicated unprivileged service user.

8. Validation note

If your deployment depends on this example directly, validate the final module in your own NixOS environment before rollout. A common check is:

nix-instantiate --parse /path/to/your/module.nix

If you integrate the example into a host configuration or flake, prefer validating it through your normal nixos-rebuild, flake check, or CI pipeline as well.