ayllu-tutorial(7) Miscellaneous Information Manual ayllu-tutorial(7)

The most basic way to use Ayllu is to change to a directory containing a Git repository and run the command ayllu-web serve. This will provide a static user interface for browsing your local repository.

This guide assumes that you have installed Ayllu on a Linux distribution with systemd.

Ayllu can be run as a regular user or as a dedicated system user. As a developer you probably want to run Ayllu as a regular system user and so we'll cover that configuration first. If you are a sysadmin and managing a public installation then you likely want to run it as a dedicated system user.

For regular users you should install a TOML file at ~/.config/ayllu/config.toml and add a few basic settings.

default_branch = "main"
[web]
blurb = """
My own personal instance of Ayllu!
"""
# enable static hosting
sites = { enabled = true }
[database]
[build]

By default Ayllu handles no persistent state directly but builds and other components require this ability. Ayllu uses a single global SQLite instance for this purpose. To enable it you can add an empty [database] section in your configuration file. By default the database will be stored in ~/.local/share/ayllu/ayllu.sqlite or /var/lib/ayllu/ayllu.sqlite.

[database]

And then run ayllu-migrate to initialize it. NOTE that prior to version 1.0 Ayllu makes no guarantees about migrations or data retention.

Ayllu can host static content from any git repository. You need to toggle the the setting in your global configuration file:

[web.sites]
enabled = true

Once enabled you can either use ayllu-shell to configure the settings of your repository or you can manually edit your repository's configuration file.

[ayllu-sites]
enabled = true
# Any site with a matching host header is served
header = Host=example.org
# Path to HTML content within the repository
content = gen
branch = master

First you should create a new configuration file at /etc/ayllu/config.toml that is owned by the root user. Your distribution may already provide you with a sample file here.

Next we'll setup a base path and configure an identity and a new collection of repositories to serve.

site_name = "Just Another Ayllu Instance"
origin = "code.example.org"
default_branch = "main"
base_path = "/var/lib/ayllu/repos"
[shell]
motd = """
Welcome to Ayllu!
"""
[[identities]]
username = "demo"
authorized_keys = [


  "... your public key here ..."
]
[[collections]]
name = "miscellaneous"
description = "disparate software written in haste"

Before we connect remotely let's run the ayllu-shell command and initialize a new repository.

sudo -u ayllu ayllu-shell

Choose "Create Repository" and follow the prompts. Of course, if you don't want to use ayllu-shell you can just create a repository manually:

sudo -u ayllu git init --bare /var/lib/ayllu/repos/miscellaneous/my-new-repo

You can now start and enable the ayllu-web service permanently.

systemctl enable ayllu-web
systemctl start ayllu-web

Next let's configure OpenSSH to delegate access to the ayllu user. WARNING: Make sure you have an alternative way to connect to your server in the event of miss-configuration We'll add a configuration drop-in at /etc/ssh/sshd_config.d/30-ayllu-keys.conf:

AuthorizedKeysCommand /usr/bin/userdbctl ssh-authorized-keys %u --chain /usr/bin/ayllu-keys %u %h %t %k
AuthorizedKeysCommandUser root

Next restart the OpenSSH process:

systemctl restart sshd

Now each time a user makes an SSH connection OpenSSH will delegate key verification to the ayllu-keys script which will grant access to any configured identities as well as allowing users to push and pull over SSH. If the verification fails the server will fall back to regular public key identification.

Now that repository is setup let's try to clone it from another computer. We assume the server is listening at code.example.org which we can verify by opening a regular SSH connection: ssh ayllu@code.example.org. With any luck you should be prompted with the ayllu-shell screen you saw in the previous step. Now that we've confirmed the shell is listening we can clone the repository over SSH: git clone ayllu@code.example.org:miscellaneous/my-new-repo.

Ayllu is designed to be run behind a reverse proxy such as Nginx.

server {


   listen 443 ssl;


   server_name forge.example.org;


   set $backend "http://127.0.0.1:10000";


   location / {


       proxy_pass $backend;


       proxy_set_header Host $host;


       proxy_set_header X-Real-IP $remote_addr;


       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;


   }


   # Hidden repositories can be password protected if desireable


   location ~ /private* {


       proxy_pass $backend;


       # include proxy.conf;


       auth_basic "private";


       auth_basic_user_file /etc/nginx/.htpasswd-private-repos;


   }
}
# Static sites can simply match a Host header such as below.
server {


   listen 443 ssl;


   server_name my-website.example.org;


 


   set $backend "http://127.0.0.1:10000";


   location / {


       proxy_pass $backend;


       proxy_set_header Host $host;


       proxy_set_header X-Real-IP $remote_addr;


       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;


   }
}
User Manual