OneImporter & OneGate on NixOS¶
NixOS differs from other Linux distributions in ways that affect the standard installation:
/etc/systemd/systemis read-only.startup.shcannot install its own systemd unit./bin/bashdoes not exist.- The Node.js runtime shipped with OneImporter is dynamically linked against a standard Linux loader.
- The
systemdbinary is not in a standard location. The check instartup.shfails.
This page describes how to run the unchanged OneImporter on NixOS. NixOS provides the systemd unit declaratively. The commands from the installation wizard stay the same, apart from a PATH prefix.
Prerequisites¶
- NixOS with root access (
sudo). - The environment ID and the server URL of your Versio.io environment. The installation wizard shows both (
Environment settings → OneImporter → Install).
Step 1: NixOS configuration¶
Add the following block to /etc/nixos/configuration.nix. Replace <environment-id> with your environment ID.
{ config, pkgs, ... }:
let
oneImporterEnv = "<environment-id>";
oneImporterDir = "/opt/versio.io/one-importer";
in
{
# Provides /bin/bash and other FHS paths for the OneImporter scripts
services.envfs.enable = true;
# Loader shim for the bundled, dynamically linked Node.js binary
programs.nix-ld.enable = true;
environment.systemPackages = with pkgs; [ wget openssl ];
systemd.services."one-importer.${oneImporterEnv}" = {
description = "Versio.io OneImporter for '${oneImporterEnv}' environment";
wants = [ "network-online.target" ];
after = [ "network-online.target" ];
wantedBy = [ "multi-user.target" ];
# Tools for self-updates and OS-level importer modules
path = [ "/run/current-system/sw" ];
unitConfig = {
StartLimitIntervalSec = 0;
# Skip the start until startup.sh has written the startup configuration
ConditionPathExists = "${oneImporterDir}/conf/service/${oneImporterEnv}/startup.conf";
};
environment = {
ONE_IMPORTER_EXECUTION_TYPE = "service";
ONE_IMPORTER_STAGE = "production";
# Optional HTTP proxy (lower case!)
# http_proxy = "http://proxy.example.com:3128";
# https_proxy = "http://proxy.example.com:3128";
# no_proxy = "localhost,127.0.0.1";
};
serviceConfig = {
EnvironmentFile = "${oneImporterDir}/src/versio.io-release.env";
ExecStart = "${oneImporterDir}/node/bin/node --max-old-space-size=4096 ${oneImporterDir}/src/one-importer.js ${oneImporterDir}/conf/service/${oneImporterEnv}/startup.conf";
WorkingDirectory = oneImporterDir;
Restart = "always";
RestartSec = "1s";
RuntimeMaxSec = "33h";
StandardOutput = "journal";
StandardError = "journal";
SyslogIdentifier = "one-importer-${oneImporterEnv}";
};
};
}
Configuration: NixOS module for the OneImporter service
Warning "One module header per file"
configuration.nixmust contain exactly one{ config, pkgs, ... }:header and one top-level attribute set. Merge theletblock and the attributes into your existing file. Do not append a second module.
Apply the configuration:
The service stays inactive for now, because startup.conf does not exist yet. This is expected.
Why each option is necessary¶
| Option | Reason |
|---|---|
services.envfs.enable |
Provides /bin/bash. The installer, startup.sh and the self-update call /bin/bash directly. |
programs.nix-ld.enable |
The bundled node binary expects a standard dynamic loader. Without it the service fails with node: No such file or directory. |
environment.systemPackages |
wget downloads the installer. openssl generates the self-signed certificates in startup.sh. |
Unit name one-importer.<environment-id> |
Same name as on other Linux distributions. startup.sh, shutdown.sh, status.sh and uninstall.sh address the unit by this name. |
path |
The self-update from the Versio.io UI runs wget and install.sh (needs tar, gzip, awk) inside the service. NixOS services only see a minimal PATH by default. OS-level modules (e.g. host inventory) also call system tools. |
ConditionPathExists |
Prevents a restart loop before the installation is complete. |
EnvironmentFile |
Loads ONE_IMPORTER_VERSION from the installed release. The configuration contains no version number, so updates need no nixos-rebuild. |
ExecStart, WorkingDirectory, Restart*, RuntimeMaxSec |
Identical to the unit generated by startup.sh. |
Table: NixOS options and their purpose
The unit deviates from the unit generated by startup.sh in these points only:
StandardOutput/StandardErrorwrite to the journal instead ofnull. The OneImporter log files underlog/service/<environment-id>/are unaffected.PIDFileis omitted. It has no effect on a unit of typesimple.After=network-online.targetreplacesAfter=network.service, which does not exist on NixOS.
Step 2: Install and start the OneImporter¶
Open the installation wizard in Versio.io (Environment settings → OneImporter → Install). Select Linux and execution as service. Run the commands from the wizard as root, with two adjustments:
- Prefix every command with
sudo. - Extend
PATHforstartup.sh. Otherwise its systemd check fails withwhich: no systemd in (…).
# Download and install (commands from the wizard)
wget -nv -N https://<versio-server>/one-importer/install.sh
sudo /bin/bash install.sh
# Configure and start (command from the wizard, with PATH prefix)
sudo env PATH="/run/current-system/systemd/bin:/run/current-system/systemd/lib/systemd:$PATH" \
/bin/bash /opt/versio.io/one-importer/startup.sh \
<environment-id> https://<versio-server> <ca-validation> <debug> <importer-modules> service
Commands: Installation on NixOS
startup.sh writes startup.conf, generates the certificates and then tries to install its own unit file. The following messages are expected and harmless:
cp: cannot create regular file '/etc/systemd/system/one-importer.<environment-id>.service': Read-only file system
chmod: cannot access '/etc/systemd/system/one-importer.<environment-id>.service': No such file or directory
Errors from systemctl enable are also harmless. NixOS already enables the unit via wantedBy. The script then starts the NixOS unit and reports its status.
Finally, authorize and activate the new instance in Versio.io (Environment settings → OneImporter → Instances). Then create an importer configuration and assign the instance (Environment settings → OneImporter → Configurations).
Verification¶
systemctl status one-importer.<environment-id>.service
journalctl -u one-importer.<environment-id>.service -b --no-pager | tail -30
sudo cat /opt/versio.io/one-importer/conf/service/<environment-id>/startup.conf
startup.conf must contain "executionType":"service" and the importer modules selected in the wizard.
Update¶
The Update and Nightly update functions in the Versio.io UI work without further steps. The service downloads the new version and exits. systemd restarts it with the new release. No nixos-rebuild is required.
For the update command from the wizard (Modify installation), run the complete command with the PATH prefix:
sudo env PATH="/run/current-system/systemd/bin:/run/current-system/systemd/lib/systemd:$PATH" \
/bin/bash -c '<update command from the wizard>'
The same applies when you change the parameters of an installation (importer modules, CA validation, debug mode).
Operation¶
sudo systemctl restart one-importer.<environment-id>.service
sudo systemctl stop one-importer.<environment-id>.service
journalctl -u one-importer.<environment-id>.service -f
- HTTP proxy: On NixOS,
startup.shcannot write proxy variables into the unit. Sethttp_proxy,https_proxyandno_proxyin theenvironmentblock of the service (see HTTP proxy usage). - Different user or group: Set
serviceConfig.UserandserviceConfig.Groupinstead ofONE_IMPORTER_USER/ONE_IMPORTER_GROUP. - Several environments on one host: Add one service block per environment ID.
Uninstall¶
- Remove the
systemd.services."one-importer.<environment-id>"block fromconfiguration.nix. - Run
sudo nixos-rebuild switch. This stops and removes the service. - Delete the installation folder:
sudo rm -rf /opt/versio.io/one-importer. - Remove the instance in Versio.io (
Environment settings → OneImporter → Instances).
Limitations¶
- Installed software: The software inventory reads the package databases of
dpkg,rpm,apkandsnap. Packages from the Nix store are not inventoried. - Configuration drift: Changes to the service (proxy, user, module list) belong in
configuration.nixor in the wizard command. Manual changes to/etcdo not survive anixos-rebuild.
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
Please run the script as a root user. |
Run the command with sudo. |
/bin/bash: No such file or directory or bad interpreter |
services.envfs.enable is not active. Apply the configuration with nixos-rebuild switch. |
Service exits immediately, journal shows node: No such file or directory |
programs.nix-ld.enable is not active, or the path in ExecStart is wrong. |
which: no systemd in (…) / OneImporter execution as service without systemd is not supported. |
startup.sh was run without the PATH prefix. |
Docker must be installed manually… |
startup.sh was run without service as the last parameter. |
OneImporter service already running |
startup.sh only runs while the service is stopped. Use the update command from the wizard, which stops the service first. |
Service stays inactive with start condition unmet |
startup.conf is missing. Run startup.sh (step 2). |
Update from the Versio.io UI fails, log shows wget: not found or tar: not found |
The path option is missing in the service block. |
error: … does not look like a module |
configuration.nix contains two module headers. Keep exactly one. |
| Instance is active, but no data is imported | No importer configuration is assigned. Create one under Environment settings → OneImporter → Configurations. |
Table: Common problems on NixOS