### Install Arion using nix-env

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Installs Arion globally using the nix-env command with a tarball from the master branch.

```bash
nix-env -iA arion -f https://github.com/hercules-ci/arion/tarball/master
```

--------------------------------

### Declare Service Startup Dependencies

Source: https://context7.com/hercules-ci/arion/llms.txt

Specifies that a service should not start until named services are running or healthy. Supports both a simple list and a structured attribute set with explicit conditions.

```nix
{
  project.name = "app-with-db";
  services.db = {
    service.image = "postgres:16";
    service.environment.POSTGRES_PASSWORD = "pass";
    service.healthcheck = {
      test = [ "CMD" "pg_isready" ];
      interval = "5s";
      retries = 10;
    };
  };
  services.app = {
    service.image = "myapp:latest";
    # Wait until db passes its healthcheck before starting
    service.depends_on = {
      db = { condition = "service_healthy"; };
    };
    service.environment.DATABASE_URL = "postgres://postgres:pass@db:5432/app";
    service.ports = [ "8080:8080" ];
  };
}
```

--------------------------------

### Add Packages to Nix-Built Images with `image.contents`

Source: https://context7.com/hercules-ci/arion/llms.txt

Specifies a list of Nix derivations whose top-level paths are added to the Docker image, serving as the primary method for installing software.

```nix
{ pkgs, ... }:
{
  project.name = "custom-image";
  services.app = {
    image.contents = [
      pkgs.nginx
      pkgs.openssl
      (pkgs.writeScriptBin "start" ''
        #!${pkgs.bash}/bin/bash
        nginx -g "daemon off;"
      '')
    ];
    image.rawConfig.Env = [ "NGINX_PORT=8080" ];
    service.ports = [ "8080:8080" ];
    service.stop_signal = "SIGQUIT";
  };
}
```

--------------------------------

### Start and Watch Arion Containers

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Use `arion up -d` to start containers in detached mode and `arion logs -f` to follow their logs. These commands are useful for quickly testing Arion projects.

```bash
$ arion up -d
$ arion logs -f
```

--------------------------------

### Pinned arion-pkgs.nix using Flake Lock

Source: https://context7.com/hercules-ci/arion/llms.txt

An `arion-pkgs.nix` example that pins Nixpkgs using a `flake.lock` file. This ensures reproducible builds by fetching a specific revision of Nixpkgs.

```nix
# arion-pkgs.nix — pinned with flake registry or npins/niv
let
  lock = builtins.fromJSON (builtins.readFile ./flake.lock);
  nixpkgsSource = lock.nodes.nixpkgs.locked;
  nixpkgs = fetchTarball {
    url = "https://github.com/NixOS/nixpkgs/archive/${nixpkgsSource.rev}.tar.gz";
    sha256 = nixpkgsSource.narHash;
  };
in import nixpkgs { system = "x86_64-linux"; }
```

--------------------------------

### NixOS Module Configuration for Arion

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/deployment.adoc

Configure Arion projects within a NixOS system. This example shows how to import the Arion NixOS module and define a project, specifying the backend and project settings. It highlights that this method reuses the host's `pkgs`.

```nix
{ 
  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 in this case
      settings = { 
        # Specify you 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 ];
      };
    };
  };
}

```

--------------------------------

### Fast Iteration with `service.useHostStore`

Source: https://context7.com/hercules-ci/arion/llms.txt

Bypasses container image creation by mounting the host's `/nix/store` directly into the container. This enables rapid local development without image rebuilds for code changes.

```nix
# arion-compose.nix
{ pkgs, ... }:
{
  project.name = "webapp";
  services.webserver = {
    image.enableRecommendedContents = true;  # adds /bin/sh and /usr/bin/env
    service.useHostStore = true;
    service.command = [ "sh" "-c" ''
      cd "$$WEB_ROOT"
      ${pkgs.python3}/bin/python -m http.server
    '' ];
    service.ports = [ "8000:8000" ];
    service.environment.WEB_ROOT = "${pkgs.nix.doc}/share/doc/nix/manual";
    service.stop_signal = "SIGINT";
  };
}
```

--------------------------------

### Run Full NixOS Systemd in Container

Source: https://context7.com/hercules-ci/arion/llms.txt

Enables the full NixOS systemd init system within a container. Configure any NixOS option under `nixos.configuration`. Use `service.useHostStore` to avoid image rebuilds during development.

```nix
# arion-compose.nix
{
  project.name = "full-nixos";
  services.webserver = { pkgs, lib, ... }:
    {
      nixos.useSystemd = true;
      nixos.configuration.boot.tmp.useTmpfs = true;
      nixos.configuration.services.nginx.enable = true;
      nixos.configuration.services.nginx.virtualHosts.localhost = {
        root = "${pkgs.nix.doc}/share/doc/nix/manual";
      };
      nixos.configuration.services.nscd.enable = false;
      nixos.configuration.system.nssModules = lib.mkForce [];
      nixos.configuration.systemd.services.nginx.serviceConfig.AmbientCapabilities =
        lib.mkForce [ "CAP_NET_BIND_SERVICE" ];
      service.useHostStore = true;
      service.ports = [ "8000:80" ];
    };
  };
}
```

--------------------------------

### Inspect Arion Project Configuration with Nix REPL

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Launch an interactive Nix REPL for your Arion project using `arion repl`. This allows you to inspect the project's configuration and Nixpkgs attributes.

```bash
$ arion repl
Launching a repl for you. To get started:

To see deployment-wide configuration
  type config. and use tab completion
To bring the top-level Nixpkgs attributes into scope
  type :a (config._module.args.pkgs) // { inherit config; }

Welcome to Nix. Type :? for help.

Loading '../../src/nix/eval-composition.nix'...
Added 5 variables.

nix-repl> config.services.webserver.service.command
[ "sh" "-c" "cd \"$$WEB_ROOT\"\n/nix/store/66fbv9mmx1j4hrn9y06kcp73c3yb196r-python3-3.8.9/bin/python -m http.server\n" ]

nix-repl> 

```

--------------------------------

### Use Docker Hub or Registry Image with `service.image`

Source: https://context7.com/hercules-ci/arion/llms.txt

Pulls and runs a Docker image from a registry. Setting this option automatically disables Nix image building.

```nix
# arion-compose.nix
{
  project.name = "db-stack";
  services.postgres = {
    service.image = "postgres:16";
    service.volumes = [ "${toString ./.}/pgdata:/var/lib/postgresql/data" ];
    service.environment = {
      POSTGRES_USER = "app";
      POSTGRES_PASSWORD = "secret";
      POSTGRES_DB = "mydb";
    };
    service.healthcheck = {
      test = [ "CMD" "pg_isready" "-U" "app" ];
      interval = "10s";
      timeout = "5s";
      retries = 5;
    };
    service.restart = "unless-stopped";
  };
}
```

--------------------------------

### Configure NixOS for Arion and Podman

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Sets up NixOS to use Arion and Podman, including enabling the Docker socket for Podman and adding the user to the 'podman' group.

```nix
{ pkgs, ... }:
{
  environment.systemPackages = [
    pkgs.arion

     # Do install the docker CLI to talk to podman.
     # Not needed when virtualisation.docker.enable = true;
    pkgs.docker-client
  ];

  # Arion works with Docker, but for NixOS-based containers, you need Podman
  # since NixOS 21.05.
  virtualisation.docker.enable = false;
  virtualisation.podman.enable = true;
  virtualisation.podman.dockerSocket.enable = true;
  virtualisation.podman.defaultNetwork.dnsname.enable = true;

  # Use your username instead of `myuser`
  users.extraUsers.myuser.extraGroups = ["podman"];
}
```

--------------------------------

### Haskell REPL for Arion

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Launch an interactive Haskell REPL for experimenting with Arion code.

```bash
repl
```

--------------------------------

### Add Shell Environment with `image.enableRecommendedContents`

Source: https://context7.com/hercules-ci/arion/llms.txt

Includes `/bin/sh` and `/usr/bin/env` in Nix-built container images, which are necessary for many standard POSIX commands and scripts.

```nix
{ pkgs, ... }:
{
  project.name = "toolbox";
  services.worker = {
    image.enableRecommendedContents = true;
    image.contents = [ pkgs.curl pkgs.jq ];
    service.command = [ "sh" "-c" "curl https://api.example.com | jq '.data'" ];
    service.environment.API_KEY = "test-key";
  };
}
```

--------------------------------

### Add or Drop Linux Capabilities

Source: https://context7.com/hercules-ci/arion/llms.txt

Provides a type-safe alternative to Docker's `cap_add`/`cap_drop`. Setting a capability to `true` adds it, `false` drops it, and omitting or `null` leaves it at Docker's default.

```nix
{
  project.name = "privileged-app";
  services.monitor = {
    service.image = "prom/node-exporter:latest";
    service.capabilities = {
      SYS_PTRACE = true;
      NET_RAW = false;
      SYS_ADMIN = false;
    };
    service.ports = [ "9100:9100" ];
    service.volumes = [
      "/proc:/host/proc:ro"
      "/sys:/host/sys:ro"
    ];
  };
}
```

--------------------------------

### Minimal arion-pkgs.nix for Nixpkgs Import

Source: https://context7.com/hercules-ci/arion/llms.txt

A basic `arion-pkgs.nix` file that imports Nixpkgs for a specific system. This is required for Arion CLI projects not using the NixOS module.

```nix
# arion-pkgs.nix — minimal
import <nixpkgs> { system = "x86_64-linux"; }
```

--------------------------------

### Run Nix-Built Arion

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Use the 'run-arion-via-nix' script to run Arion built with Nix for a consistent environment.

```bash
run-arion-via-nix
```

--------------------------------

### Run Arion with Quick Updates

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Use this command for a fast iteration cycle when developing Arion modules. Note that the arion command logic might be outdated.

```bash
~/src/arion/run-arion-quick up -d
```

--------------------------------

### Build Arion Project with Nix

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Build an Arion project using `nix-build` with a Nix expression that specifies the modules and package set. This is useful for creating deployable artifacts.

```nix
arion.build { modules = [ ./arion-compose.nix ]; pkgs = import ./arion-pkgs.nix; }
```

--------------------------------

### Run Root Commands During Image Build with `image.fakeRootCommands`

Source: https://context7.com/hercules-ci/arion/llms.txt

Executes shell commands within the image's root context during `dockerTools.buildLayeredImage`. Useful for tasks like directory creation or permission adjustments.

```nix
{ pkgs, ... }:
{
  project.name = "prepared-app";
  services.api = {
    image.contents = [ pkgs.nodejs ];
    image.fakeRootCommands = ''
      mkdir -p /app /var/log/app
      chmod 777 /var/log/app
      echo '{"port": 3000}' > /app/config.json
    '';
    service.command = [ "${pkgs.nodejs}/bin/node" "/app/server.js" ];
    service.ports = [ "3000:3000" ];
  };
}
```

--------------------------------

### Arion CLI Commands for Service Management

Source: https://context7.com/hercules-ci/arion/llms.txt

Manage Docker Compose services using Arion's CLI. Commands include `up`, `down`, `logs`, `repl`, `push`, and `cat`. The `repl` command opens an interactive Nix REPL pre-loaded with the composition.

```bash
# Start all services in detached mode
arion up -d

# Follow aggregated logs from all services
arion logs -f

# Rebuild and recreate a specific service
arion up -d --always-recreate-deps webserver

# Stop and remove containers
arion down

# Launch an interactive Nix REPL on the composition
arion repl
# Inside the repl:
# nix-repl> config.services.webserver.service.command
# nix-repl> :a (config._module.args.pkgs) // { inherit config; }
# nix-repl> config.services.webserver.nixos.evaluatedConfig.services.nginx.enable

# Push built images to a registry
arion push

# Print the generated docker-compose.yaml
arion cat
```

--------------------------------

### Configure Arion NixOS Module

Source: https://context7.com/hercules-ci/arion/llms.txt

Integrate Arion projects as systemd services on NixOS using the `virtualisation.arion` module. Supports `podman-socket` or `docker` backends. Ensure `virtualisation.podman.enable` and `virtualisation.podman.dockerSocket.enable` are set for the `podman-socket` backend.

```nix
# /etc/nixos/configuration.nix
{
  imports = [
    arion.nixosModules.arion  # from flake input
  ];

  virtualisation.arion = {
    backend = "podman-socket";  # or "docker"
    projects.myapp = {
      serviceName = "myapp";   # optional; defaults to "arion-myapp"
      settings = {
        imports = [ ./arion-compose.nix ];
        # project.name defaults to the attribute key ("myapp")
      };
    };
  };

  # Required for podman-socket backend:
  # (set automatically by nixos-module.nix)
  # virtualisation.podman.enable = true;
  # virtualisation.podman.dockerSocket.enable = true;
}
```

--------------------------------

### Run Arion Unit Tests

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Execute the 'live-unit-tests' script to run the test suite. Note that only the test suite itself is 'live'.

```bash
live-unit-tests
```

--------------------------------

### Run Incrementally Built Arion

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Execute the 'run-arion' script to run Arion with incrementally built changes.

```bash
run-arion
```

--------------------------------

### Full NixOS Arion compose file

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Configures a full NixOS system within a container, enabling Nginx and setting up a virtual host. It uses systemd and requires specific capabilities for Nginx.

```nix
{ pkgs, lib, ... }:
{
  project.name = "full-nixos";
  services.webserver = { pkgs, lib, ... }:
  {
    nixos.useSystemd = true;
    nixos.configuration.boot.tmp.useTmpfs = true;
    nixos.configuration.services.nginx.enable = true;
    nixos.configuration.services.nginx.virtualHosts.localhost.root = "${pkgs.nix.doc}/share/doc/nix/manual";
    nixos.configuration.services.nscd.enable = false;
    nixos.configuration.system.nssModules = lib.mkForce [];
    nixos.configuration.systemd.services.nginx.serviceConfig.AmbientCapabilities = 
      lib.mkForce [ "CAP_NET_BIND_SERVICE" ];
    service.useHostStore = true;
    service.ports = [
      "8000:80" # host:container
    ];
  };
}
```

--------------------------------

### Minimal Arion compose file

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Defines a minimal web server service using Arion, running a Python HTTP server on port 8000. It utilizes nixpkgs and sets the WEB_ROOT environment variable.

```nix
{ pkgs, ... }:
{
  project.name = "webapp";
  services = {

    webserver = {
      image.enableRecommendedContents = true;
      service.useHostStore = true;
      service.command = [ "sh" "-c" ''
                  cd "$$WEB_ROOT"
                  ${pkgs.python3}/bin/python -m http.server
                '' ];
      service.ports = [
        "8000:8000" # host:container
      ];
      service.environment.WEB_ROOT = "${pkgs.nix.doc}/share/doc/nix/manual";
      service.stop_signal = "SIGINT";
    };
  };
}
```

--------------------------------

### Build Arion Project with runArion

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

If deploying with `runArion`, you can use a simplified Nix expression for building, provided your `pkgs` variable is set correctly. This integrates Arion builds into the Hercules CI effects system.

```nix
let
  deployment = pkgs.effects.runArion { /* ... */ });
in deployment.prebuilt
```

--------------------------------

### Build and Typecheck Arion

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Use the 'build' script for typechecking the Arion Haskell code.

```bash
build
```

--------------------------------

### Define Custom Docker Networks

Source: https://context7.com/hercules-ci/arion/llms.txt

Declares named Docker networks with IPAM, drivers, and other options. A default network named after `project.name` is always created unless `enableDefaultNetwork = false`.

```nix
{ lib, pkgs, ... }:
{
  project.name = "multi-net";
  networks.backend = {
    driver = "bridge";
    ipam.config = [{ subnet = "10.10.0.0/24"; gateway = "10.10.0.1"; }];
  };
  networks.frontend = {
    driver = "bridge";
    ipam.config = [{ subnet = "10.20.0.0/24"; }];
  };

  services.proxy = {
    service.image = "nginx:alpine";
    service.networks = [ "frontend" "backend" ];
    service.ports = [ "80:80" ];
  };
  services.db = {
    service.image = "postgres:16";
    service.networks = {
      backend = { ipv4_address = "10.10.0.10"; };
    };
    service.environment.POSTGRES_PASSWORD = "pass";
  };
}
```

--------------------------------

### Limit Block I/O Throttling for Services

Source: https://context7.com/hercules-ci/arion/llms.txt

Limits or weights block I/O for a service, useful for preventing runaway disk usage from one container from starving others.

```nix
{
  project.name = "io-limited";
  services.heavy-writer = {
    service.image = "ubuntu:22.04";
    service.command = [ "bash" "-c" "while true; do dd if=/dev/zero of=/tmp/test bs=1M count=100; done" ];
    service.blkio_config = {
      weight = 300;
      device_write_bps = [{ path = "/dev/sda"; rate = "10mb"; }];
      device_read_bps  = [{ path = "/dev/sda"; rate = "20mb"; }];
    };
  };
}
```

--------------------------------

### Programmatic Nix API for Arion

Source: https://context7.com/hercules-ci/arion/llms.txt

Exposes Nix library functions for programmatic use. `lib.eval` returns the full evaluated module set, while `lib.build` returns the `docker-compose.yaml` derivation directly.

```nix

```

--------------------------------

### Live Check Arion

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Use the 'live-check' script for continuous typechecking during development.

```bash
live-check
```

--------------------------------

### DockerHub image Arion compose file

Source: https://github.com/hercules-ci/arion/blob/main/docs/modules/ROOT/pages/index.adoc

Defines a PostgreSQL service using a Docker Hub image. It configures the image, volumes for data persistence, and the PostgreSQL password.

```nix
{
  services.postgres = {
    service.image = "postgres:10";
    service.volumes = [ "${toString ./.}/postgres-data:/var/lib/postgresql/data" ];
    service.environment.POSTGRES_PASSWORD = "mydefaultpass";
  };
}
```

--------------------------------

### Attach Metadata Labels to Containers

Source: https://context7.com/hercules-ci/arion/llms.txt

Attaches Docker labels to containers, commonly used for Traefik routing rules, monitoring scrapers, or deployment metadata.

```nix
{ pkgs, ... }:
{
  project.name = "traefik-app";
  services.api = {
    image.command = [ "${pkgs.python3}/bin/python" "-m" "http.server" "8000" ];
    service.useHostStore = true;
    service.labels = {
      "traefik.enable" = "true";
      "traefik.http.routers.api.rule" = "Host(`api.localhost`)";
      "traefik.http.routers.api.entrypoints" = "web";
      "traefik.http.services.api.loadBalancer.server.port" = "8000";
    };
    service.networks = [ "traefik-net" ];
  };
}
```

--------------------------------

### Evaluate Arion Composition in Nix Expression

Source: https://context7.com/hercules-ci/arion/llms.txt

Use `builtins.getFlake` to access Arion and its evaluation functions within a Nix expression. This allows for accessing any configuration attribute of the composition.

```nix
let
  arion = builtins.getFlake "github:hercules-ci/arion";
  pkgs = import <nixpkgs> {};
in {
  # Evaluate the full composition (access any config attribute)
  composition = arion.lib.eval {
    pkgs = pkgs;
    modules = [ ./arion-compose.nix ];
  };

  # Build just the docker-compose.yaml derivation
  composeFile = arion.lib.build {
    pkgs = pkgs;
    modules = [ ./arion-compose.nix ];
  };
  # composeFile is now a path to a docker-compose.yaml in the Nix store
  # nix-build -A composeFile  →  /nix/store/...-docker-compose.yaml
}
```

--------------------------------

### Set Docker Compose Project Name with `project.name`

Source: https://context7.com/hercules-ci/arion/llms.txt

Sets the COMPOSE_PROJECT_NAME to prevent Arion from deriving a name from the checkout directory. This is a required composition-level option.

```nix
# arion-compose.nix
{ pkgs, ... }:
{
  project.name = "myapp";  # becomes COMPOSE_PROJECT_NAME=myapp

  services.api = {
    service.image = "node:20";
    service.command = [ "node" "server.js" ];
    service.ports = [ "3000:3000" ];
  };
}
```

--------------------------------

### Update Arion Command Logic

Source: https://github.com/hercules-ci/arion/blob/main/HACKING.md

Remove the cached result to ensure the arion command logic is updated on the next run.

```bash
rm ~/src/arion/result-run-arion-quick
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.