runArion

runArion :: AttrSet → Effect

Perform an Arion deployment, like arion up -d.

This function supports two styles of invocation, as illustrated in the examples:

arion-pkgs.nix-based:

pkgs.effects.runArion {
  name = "neat-project";
  # requires ./arion-compose.nix and ./arion-pkgs.nix
  directory = ./.;
  userSetupScript = ''
    # ...
  '';
}

or pkgs reuse:

pkgs.effects.runArion {
  name = "neat-project";
  # ignores arion-pkgs.nix even if present
  modules = ./neat-project-arion-compose.nix;
  userSetupScript = ''
    # ...
  '';
}

Parameters

name

The Docker Compose project name.

directory

Required unless modules is set.

Uses the arion-compose.nix and arion-pkgs.nix files inside the passed directory.

modules

Required unless directory is set.

Use the specified modules in place or arion-compose.nix. Uses the pkgs that you passed to hercules-ci-effects instead of arion-pkgs.nix, unless you also set pkgs.

Example:

modules = [
  ./alternate-compose.nix
  { config.services.webserver.service.useHostStore = false; }
];

pkgs

Nixpkgs invocation, optional.

If directory is not given, pkgs will default to the Nixpkgs that runArion linked to.

Example:

pkgs = import ./pinned-nixpkgs.nix { system = "x86_64-linux"; };

uid

This parameter is intended for local development only and usually does not have a well-defined meaning in the context of a remote deployment.

By default, any use of the uid parameter inside the deployment will cause an error.

hostNixStorePrefix

Prefixes store paths on the host, allowing the Nix store to be stored at an alternate location without altering the format of store paths.

secretsMap

Example:

secretsMap.docker = "default-docker";

userSetupScript

Example:

userSetupScript = ''
    # Uses secretsMap.docker value
    writeDockerKey
    useDockerHost 203.0.113.2 12376
  '';

…​ — remaining arguments

Other attributes are passed to mkEffect, which passes its remaining arguments to mkDerivation.

Return value

An effect that updates the Arion project as configured.

The effect has the following attributes in addition to the attributes returned by mkEffect.

config

The config parameter of the module system. This can be used to inspect the system configuration before committing it. For example:

nix repl ci.nix
nix-repl> my-arion.config.services.web.image.name
"my-web"

prebuilt

A derivation representing the built configuration file.

prebuilt.config

Same as config.

See also

  • runNixOps — provision cloud resources and VM-based networks of NixOS machines

  • writeDockerKey — write Docker TLS credentials from a secret

  • useDockerHost — set environment to use a Docker host