Running as a Container

The quickest way to get started running Ayllu is by using a container. Podman is the only supported container platform although Docker may work as well.

There are several different configurations that can be used to run Ayllu as a container.

Rootless Container with Ayllu Running as Root

This configuration works best if you want Ayllu to have access to your repositories for browsing your code locally. The tutorial assumes that you have permissions to access all of your code repositories.Note that the commands below use a separate configuration and data paths to avoid conflicting with the default paths if the Ayllu binary is installed directly on your system.

First create configuration and data paths that we will map into the container.

mkdir ~/.config/ayllu-podman
mkdir ~/.local/share/ayllu-podman

Next pull the latest version of the container and generate a new configuration file.

podman pull registry.ayllu-forge.org/projects/ayllu:main
podman run --rm -ti registry.ayllu-forge.org/projects/ayllu:main ayllu config generate > ~/.config/ayllu-podman/config.toml

The next step is to map "collections" (directories that contain git repositories) into the Ayllu container. On my system I keep active projects I'm working on in a directory called ~/repos/projects and I keep past projects for reference in a directory called ~/repos/attic.

...
[[collections]]
name = "projects"
description = "active projects"
# ~/repos/projects --> /repos in the container
path = "/repos/projects"

[[collections]]
name = "attic"
description = "past projects stowed away in the attic"
path = "/repos/attic"
...

Now you can start the container ensuring that you map the code collection into the correct path which you configured in the step above. In the commands below we will use the following volume maps from my host system into the container. Take a look at the Podman rootless tutorial for a refresher on how rootless volume mappings work. Note that below the repositories are mounted as :rw. This is because Ayllu uses Git worktrees to run certain types of analysis such as the code composition chart. If you don't care about that you can change this to read-only to prevent any write access at all.

# code repositories
-v ~/repos:/repos:rw
# configuration directory
-v ~/.config/ayllu-podman:/root/.config/ayllu
# stateful sqlite database
-v ~/.local/share/ayllu-podman:/root/.local/share/ayllu

Finally we can launch the actual container.

podman run \
    --net host --rm -ti --user root \
    -v ~/repos:/repos \
    -v ~/.config/ayllu-podman:/root/.config/ayllu \
    -v ~/.local/share/ayllu-podman:/root/.local/share/ayllu \
    registry.ayllu-forge.org/projects/ayllu:main \
    ayllu serve

You should now be able to browse to the user interface at localhost:8080.

Configure with Systemd

You can also configure the container to run as a systemd-user service. See the documentation for podman systemd units. You can also checkout the archlinux wiki for a tutorial.

Here is an example file at ~/.config/containers/systemd/ayllu.container.

[Unit]
Description=Ayllu Container

[Container]
ContainerName=ayllu
Image=registry.ayllu-forge.org/projects/ayllu:main
Network=host
User=root
Volume=%h/repos:/repos:rw
Volume=%h/.config/ayllu-podman:/root/.config/ayllu
Volume=%h/.local/share/ayllu-podman:/root/.local/share/ayllu
Exec=ayllu serve

[Service]
Restart=on-failure

# Extend Timeout to allow time to pull the image
TimeoutStartSec=300

# The [Install] section allows enabling the generated service.
[Install]
WantedBy=default.target

Once you've configured the file you can install and run it:

# validate the configuration
/usr/lib/podman/quadlet -user -dryrun
# install generated systemd services
/usr/lib/podman/quadlet -user ~/.config/systemd/user
# reload the user daemon
systemctl --user daemon-reload
# start the ayllu container
systemctl --user start ayllu

If all went well Ayllu should now be running as a container managed by systemd!

Rootless with a non-root User within a Container

This method is the most restricted technique for running Ayllu in a production deployment. Not fully supported yet, TODO.

As Root with Ayllu Running as a Non-root User

This method is a hybrid approach that is useful for serving components of Ayllu from a container but also retaining a system level installation. Not fully supported yet, TODO.

Distribution Packages

NOTE: Few distribution packages currently exist for Ayllu, any contributions in this regard would be gladly accepted!

From Source

TODO