Docker image

We provide official images which can be found under:

  • docker registry arcan1s/ahriman;

  • ghcr.io registry ghcr.io/arcan1s/ahriman.

These images are totally identical.

Docker image is being updated on each commit to master as well as on each version. If you would like to use last (probably unstable) build you can use edge tag or latest for any tagged versions; otherwise you can use any version tag available.

The default action (in case if no arguments provided) is repo-update. Basically the idea is to run container, e.g.:

docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest

In order to make data available outside of container, you would need to mount local (parent) directory inside container by using -v /path/to/local/repo:/var/lib/ahriman argument, where /path/to/local/repo is a path to repository on local machine. In addition, you can pass own configuration overrides by using the same -v flag, e.g.:

docker run --privileged -v /path/to/local/repo:/var/lib/ahriman -v /path/to/overrides/overrides.ini:/etc/ahriman.ini.d/10-overrides.ini arcan1s/ahriman:latest

The action can be specified during run, e.g.:

docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest package-add ahriman --now

For more details please refer to the docker FAQ.

Privileged and non-privileged container

Examples here suggest using --privileged flag which is required for the devtools and is involved in two types of operations: tmpfs mount and cgroup manipulation. Whereas it is the easiest way to operate, it might be not really secure. The other way to make devtools working is to grant required capabilities, which can be achieved by using flags:

  • --cap-add=SYS_ADMIN, which grants permissions to operate with tmpfs for systemd-nspawn.

  • -v /sys/fs/cgroup:/sys/fs/cgroup which allows access to cgroup manipulation.

Thus, there are two possible ways to run the container:

docker run --privileged arcan1s/ahriman:latest

and

docker run --cap-add=SYS_ADMIN -v /sys/fs/cgroup:/sys/fs/cgroup arcan1s/ahriman:latest

but for the simplicity this FAQ will always use --privileged flag.

Environment variables

The following environment variables are supported:

  • AHRIMAN_ARCHITECTURE - architecture of the repository, default is x86_64.

  • AHRIMAN_DEBUG - if set all commands will be logged to console.

  • AHRIMAN_FORCE_ROOT - force run ahriman as root instead of guessing by subcommand.

  • AHRIMAN_HOST - host for the web interface, default is 0.0.0.0.

  • AHRIMAN_MULTILIB - if set (default) multilib repository will be used, disabled otherwise.

  • AHRIMAN_OUTPUT - controls logging handler, e.g. syslog, console. The name must be found in logging configuration. Note that if syslog handler is used you will need to mount /dev/log inside container because it is not available there.

  • AHRIMAN_PACKAGER - packager name from which packages will be built, default is ahriman bot <ahriman@example.com>.

  • AHRIMAN_PACMAN_MIRROR - override pacman mirror server if set.

  • AHRIMAN_PORT - HTTP server port if any, default is empty.

  • AHRIMAN_POSTSETUP_COMMAND - if set, the command which will be called (as root) after the setup command, but before any other actions.

  • AHRIMAN_PRESETUP_COMMAND - if set, the command which will be called (as root) right before the setup command.

  • AHRIMAN_REPOSITORY - repository name, default is aur.

  • AHRIMAN_REPOSITORY_SERVER - optional override for the repository URL. Useful if you would like to download packages from remote instead of local filesystem.

  • AHRIMAN_REPOSITORY_ROOT - repository root. Because of filesystem rights it is required to override default repository root. By default, it uses ahriman directory inside ahriman’s home, which can be passed as mount volume.

  • AHRIMAN_UNIX_SOCKET - full path to unix socket which is used by web server, default is empty. Note that more likely you would like to put it inside AHRIMAN_REPOSITORY_ROOT directory (e.g. /var/lib/ahriman/ahriman/ahriman-web.sock) or to /run/ahriman.

  • AHRIMAN_USER - ahriman user, usually must not be overwritten, default is ahriman.

  • AHRIMAN_VALIDATE_CONFIGURATION - if set (default) validate service configuration.

You can pass any of these variables by using -e argument, e.g.:

docker run --privileged -e AHRIMAN_PORT=8080 -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest

Daemon service

There is special repo-daemon subcommand which emulates systemd timer and will perform repository update periodically:

docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest repo-daemon

This command uses same rules as repo-update, thus, e.g. requires --privileged flag. Check also examples.

Web service setup

For that you would need to have web container instance running forever; it can be achieved by the following command:

docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest

Note about AHRIMAN_PORT environment variable which is required in order to enable web service. An additional port bind by -p 8080:8080 is required to pass docker port outside of container.

The AHRIMAN_UNIX_SOCKET variable is not required, however, highly recommended as it can be used for interprocess communications. If you set this variable you would like to be sure that this path is available outside of container if you are going to use multiple docker instances.

If you are using AHRIMAN_UNIX_SOCKET variable, for every next container run it has to be passed also, e.g.:

docker run --privileged -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest

Otherwise, you would need to pass AHRIMAN_PORT and mount container network to the host system (--net=host), e.g.:

docker run --privileged --net=host -e AHRIMAN_PORT=8080 -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest

Simple server with authentication can be found in examples too.

Multi-repository web service

Idea is pretty same as to just run web service. However, it is required to run setup commands for each repository, except for one which is specified by AHRIMAN_REPOSITORY and AHRIMAN_ARCHITECTURE variables.

In order to create configuration for additional repositories, the AHRIMAN_POSTSETUP_COMMAND variable should be used, e.g.:

docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -e AHRIMAN_POSTSETUP_COMMAND="ahriman --architecture x86_64 --repository aur-v2 service-setup --build-as-user ahriman --packager 'ahriman bot <ahriman@example.com>'" -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest

The command above will also create configuration for the repository named aur-v2.

Note, however, that the command above is only required in case if the service is going to be used to run subprocesses. Otherwise, everything else (web interface, status, etc) will be handled as usual.

Configuration example.