serene-aur

serene is an easy to deploy, self-hosted, AUR build server that aims at replacing your AUR helper.

This project aims to solve some inconveniences when using AUR packages. It is often annoying having to build your AUR packages on every device when a new version arrives. Existing prebuilt repositories often don't quite do the trick as they don't have all the software you need. Current self-hosted solutions are not flexible enough and cumbersome to maintain.

This is where serene comes in. It is a self-hosted package repository and build server which is intended to be really flexible and easy to use, to the point of it being able to replace an AUR helper. It makes heavy use of containerization for easier setup and clean builds. These are the main features:

Easy Hosting: The whole setup is just one docker container, making it easy to host.
Powerful CLI: You can add, build, remove and diagnose the packages you want to build easily from your shell via the CLI.
Flexibility: Customize setup commands, building schedule, etc. on a per-package basis and even use custom non-aur repositories.

Are you ready to host your own? Head to the deploying section to deploy a server and install the cli, then look at some basic usage.

Usage

This section briefly covers how one uses the system as an end user, via the included cli. See installation for information about how to deploy the server and install the CLI locally.

Add a package from the AUR to the repository, so that it is built automatically:

serene add my-package

List all currently managed packages, their version and build status:

serene list

Get more specific information about a package as well as the past builds:

serene info my-package

Setup commands to run before building the package:

serene info my-package set prepare "add some keys && do something else"

Many more commands are found on the documentation for the CLI:

CLI Documentation

State

This project is still in its early stages, but already usable on a daily basis. There are also a couple of features and improvements that still need to be implemented. Notable missing features include:

Entirely custom PKGBUILDs without a git repository
Package signing
Automatic AUR dependency resolving (#4)

Refer to the TODO File for more features, tasks and enhancements and don't hesitate to contribute if interested.

Installation

Installing serene involves two things, deploying the server, and installing a local CLI to conveniently interact with the server.

Deploying

Here is a quick overview of hosting a serene server, based on the main branch. The server is just a single docker container, making it straightforward:

First, create an empty file called authorized_secrets in your directory.
Set up a reverse proxy for docker (e.g. traefik) to use SSL/TLS.
Add the following service to your docker compose in the same directory:

# docker-compose.yml > services

serene:
  image: ghcr.io/virtcode/serene-aur:main
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - ./authorized_secrets:/app/authorized_secrets
  labels:
    - "your traefik labels here (the server is open on 80)"

Now you are done and can start your deployment. Note that the container requires write access to the docker socket so that it can spin up containers for building the package. See the full server documentation for more information:

Server Documentation Runner Documentation

Installing the CLI

To start using your server, you should install the corresponding cli to communicate with the server to download and build packages. You have the following options to install the cli:

Build via makepkg: You can download and build the corresponding PKGBUILD manually on your system, and install the package.
Download Manually: Your server will automatically build the cli by default. If you have not yet added the server to your repositories, you can download the package manually by heading to https://your-host/x86_64 and finding the package called serene-cli. Install it with pacman.
Add the Repository: As the cli is built by default, you could already add as a repository to pacman, as seen below. Now install serene-cli with pacman.
Build Manually: You can also build it completely manually from source.

The CLI is available under serene. You can now run it in your terminal, and it will tell you the next steps. It'll walk you through adding the repository to your pacman config and adding your secret to your server. For all the other features, see the full documentation:

CLI Documentation

Installing only the Repository

If you want to use the repository without instructions from the cli, also quite easy. The hosted server can be used as a normal pacman repository, by adding it to /etc/pacman.conf:

[serene]
SigLevel = Optional TrustAll
Server = https://your-host/x86_64

Signatures are not validated, as this is not yet supported. This shouldn't be an issue as we're using https and don't have any mirrors.

Architecture

Here's a very quick word about the architecture of serene:

Server Container: API and file Server for the repository. Manages all the packages and schedules.
Runner Container: Spun up by the Server Container as a sibling container on the host. Build only one package each.
Local CLI: Interacts with said API to add and manipulate added packages. Requires authentication via secret.

Disclaimer

When hosting a repository with this project, this repository is your responsibility!

This means that it is your job to check PKGBUILDs before adding a package to the repository, as building the packages on an isolated environment does in no way protect you from malware if you install the package on your system. So make sure you trust the software and AUR package maintainers before adding it into the repository. This is especially important as the server will automatically build new versions without any actions from your side.

License

This project is licensed under the MIT License, see the LICENSE file for more information.

dumbasPL/serene-aur