Skip to content

OneImporter & OneGate on NixOS

NixOS differs from other Linux distributions in ways that affect the standard installation:

  • /etc/systemd/system is read-only. startup.sh cannot install its own systemd unit.
  • /bin/bash does not exist.
  • The Node.js runtime shipped with OneImporter is dynamically linked against a standard Linux loader.
  • The systemd binary is not in a standard location. The check in startup.sh fails.

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.nix must contain exactly one { config, pkgs, ... }: header and one top-level attribute set. Merge the let block and the attributes into your existing file. Do not append a second module.

Apply the configuration:

sudo nixos-rebuild switch

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/StandardError write to the journal instead of null. The OneImporter log files under log/service/<environment-id>/ are unaffected.
  • PIDFile is omitted. It has no effect on a unit of type simple.
  • After=network-online.target replaces After=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:

  1. Prefix every command with sudo.
  2. Extend PATH for startup.sh. Otherwise its systemd check fails with which: 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.sh cannot write proxy variables into the unit. Set http_proxy, https_proxy and no_proxy in the environment block of the service (see HTTP proxy usage).
  • Different user or group: Set serviceConfig.User and serviceConfig.Group instead of ONE_IMPORTER_USER/ONE_IMPORTER_GROUP.
  • Several environments on one host: Add one service block per environment ID.

Uninstall

  1. Remove the systemd.services."one-importer.<environment-id>" block from configuration.nix.
  2. Run sudo nixos-rebuild switch. This stops and removes the service.
  3. Delete the installation folder: sudo rm -rf /opt/versio.io/one-importer.
  4. Remove the instance in Versio.io (Environment settings → OneImporter → Instances).

Limitations

  • Installed software: The software inventory reads the package databases of dpkg, rpm, apk and snap. Packages from the Nix store are not inventoried.
  • Configuration drift: Changes to the service (proxy, user, module list) belong in configuration.nix or in the wizard command. Manual changes to /etc do not survive a nixos-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