Arion Documentation

Arion projects can be integrated into a NixOS configuration. This approach allows for efficient transfers using Nix's copy-closure algorithm and utilizes transparent binary caches instead of a stateful Docker registry.

Important Note: This deployment method does NOT use an arion-pkgs.nix file; it reuses the host's pkgs instead.

To use this, add the Arion NixOS module to your imports. Depending on how you use Arion, choose one of the following import methods:

• NIV: ((import ./nix/sources.nix).arion + "/nixos-module.nix")
• Flakes: arion.nixosModules.arion (where arion is a flake input)
• Other: Use builtins.fetchTarball with the specific commit hash of Arion.

Configure the project under virtualisation.arion.

{
  imports = [
    # Pick one of:
    #  - niv
    ((import ./nix/sources.nix).arion + "/nixos-module.nix")
    #  - or flakes (where arion is a flake input)
    arion.nixosModules.arion
    #  - or other: copy commit hash of arion and replace HASH in:
    (builtins.fetchTarball "https://github.com/hercules-ci/arion/archive/HASH.tar.gz" + "/nixos-module.nix")
  ];

  virtualisation.arion = {
    backend = "podman-socket"; # or "docker"
    projects.example = {
      serviceName = "example"; # optional systemd service name, defaults to arion-example
      settings = {
        # Specify your project here, or import it from a file.
        # NOTE: This does NOT use ./arion-pkgs.nix, but defaults to NixOS' pkgs.
        imports = [ ./arion-compose.nix ];
      };
    };
  };
}

These options can be applied to most Arion commands to configure the Nix evaluation and Docker Compose behavior.

• -f, --file FILE: Specify one or more configuration files. If multiple are provided, they are merged. Defaults to ./arion-compose.nix.
• -p, --pkgs EXPR: Use the Nix expression EXPR to obtain the Nixpkgs attribute set used for bootstrapping and evaluation. Defaults to ./arion-pkgs.nix.
• --nix-arg ARG: Pass an extra argument to the Nix evaluator. Example: --nix-arg --option --nix-arg substitute --nix-arg false.
• --prebuilt-file JSONFILE: Use a prebuilt JSON file instead of evaluating Nix expressions. This causes other evaluation-related options to be ignored.
• --no-ansi: Avoid ANSI control sequences in output.
• --compatibility: If set, Docker Compose will attempt to convert deploy keys in v3 files to their non-Swarm equivalent.
• --log-level LEVEL: Set the log level to DEBUG, INFO, WARNING, ERROR, or CRITICAL.

# Example usage with custom files and nix args
arion -f custom-compose.nix -p custom-pkgs.nix --nix-arg --option flag true up

Arion passes many standard Docker Compose commands through to the underlying engine. These are grouped by their effect on the lifecycle of the services:

Build/Lifecycle Commands:

• build: Build or rebuild services.
• bundle: Generate a Docker bundle from the Compose file.
• create: Create services.
• pull: Pull service images.
• push: Push service images.
• restart: Restart services.
• run: Run a one-off command.
• scale: Set number of containers for a service.
• start: Start services.
• up: Create and start containers.

Management/State Commands:

• config: Validate and view the Compose file.
• down: Stop and remove containers, networks, images, and volumes.
• events: Receive real-time events from containers.
• images: List images.
• kill: Kill containers.
• logs: View output from containers.
• pause: Pause services.
• port: Print the public port for a port binding.
• ps: List containers.
• rm: Remove stopped containers.
• stop: Stop services.
• top: Display the running processes.
• unpause: Unpause services.

Utility Commands:

• help: Get help on a command.
• version: Show the Docker-Compose version information.

The exec command allows you to run a command inside a running service container.

Usage: arion exec [OPTIONS] SERVICE [COMMAND] [ARGS...]

Options:

• -d, --detach: Run the command in the background.
• --privileged: Give extended privileges to the process.
• -u, --user USER: Run the command as this user.
• -T: Disable pseudo-tty allocation.
• --index INDEX: Index of the container if there are multiple instances of a service (must be >= 1).
• -e, --env KEY=VALUE: Set environment variables (can be used multiple times).
• -w, --workdir DIR: Working directory in which to start the command in the container.

If no COMMAND is provided, Arion attempts to use the defaultExec defined in the service configuration. If that is also missing, it defaults to /bin/sh.

# Run a command as root in the 'web' service
arion exec --user root web ls /app

# Run a detached command with an environment variable
arion exec -d -e DEBUG=true web python manage.py migrate

# Run in a specific container instance (index 2)
arion exec --index 2 web top