mirror of
https://github.com/rustfs/rustfs.git
synced 2026-07-27 16:48:58 +00:00
houseme
4648de9e62
* fix(deploy): simplify systemd service startup * docs(deploy): add nixos systemd service example * docs(deploy): add nixos service guide * chore(deps): update pulsar and pyroscope * docs(deploy): refine nixos service guidance * fix(deploy): use explicit rustfs server entrypoint
113 lines
3.9 KiB
Markdown
113 lines
3.9 KiB
Markdown
# RustFS NixOS Service Guide
|
|
|
|
This guide explains how to use [rustfs.nixos.service.nix](./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:
|
|
|
|
```nix
|
|
{
|
|
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:
|
|
|
|
```nix
|
|
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:
|
|
|
|
```nix
|
|
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:
|
|
|
|
```bash
|
|
sudo nixos-rebuild switch
|
|
sudo systemctl enable --now rustfs
|
|
```
|
|
|
|
## 6. Verify readiness and logs
|
|
|
|
Check whether `systemd` sees the service as fully ready:
|
|
|
|
```bash
|
|
systemctl status rustfs
|
|
systemctl show rustfs -p Type -p ActiveState -p SubState
|
|
```
|
|
|
|
Follow the service logs:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|