docs: started rewriting everything

cron-docs
Jef Roosens 2022-05-06 19:14:09 +02:00
parent a3b6680153
commit cf7744993d
Signed by: Jef Roosens
GPG Key ID: B75D4F293C7052DB
8 changed files with 128 additions and 49 deletions

View File

@ -9,12 +9,12 @@ documentation might not be relevant anymore for the latest release.
## Overview ## Overview
Vieter has a few main features: Vieter consists of two main parts:
* It's a simple & lightweight implementation of an Arch repository server * A lightweight implementation of an Arch repository, including routes for
* It allows for uploading of built package archives uploading built package archives.
* It supports a basic build system to periodically re-build packages & upload * A cron daemon implementation designed to periodically rebuild a given list of
them to the server packages, given a Git repository containing their PKGBUILD.
{{< hint info >}} {{< hint info >}}
**Note** **Note**

View File

@ -56,7 +56,7 @@ Vieter only supports uploading archives compressed using either gzip, zstd or
xz at the moment. xz at the moment.
{{< /hint >}} {{< /hint >}}
## API ## Repos API
All API routes require the API key to provided using the `X-Api-Key` header. All API routes require the API key to provided using the `X-Api-Key` header.
Otherwise, they'll return a status code 401. Otherwise, they'll return a status code 401.
@ -69,7 +69,7 @@ Returns the current list of Git repositories.
Get the information for the Git repo with the given ID. Get the information for the Git repo with the given ID.
### `POST /api/repos?<url>&<branch>&<arch>&<repo>` ### `POST /api/repos?<url>&<branch>&<repo>`
Adds a new Git repository with the provided URL, Git branch & comma-separated Adds a new Git repository with the provided URL, Git branch & comma-separated
list of architectures. list of architectures.
@ -78,7 +78,7 @@ list of architectures.
Deletes the Git repository with the provided ID. Deletes the Git repository with the provided ID.
### `PATCH /api/repos/<id>?<url>&<branch>&<arch>&<repo>` ### `PATCH /api/repos/<id>?<url>&<branch>&<arch>&<repo>&<schedule>`
Updates the provided parameters for the repo with the given ID. All arguments Updates the provided parameters for the repo with the given ID. All arguments
are optional. are optional.

View File

@ -1,8 +1,8 @@
# Builder # Building Packages
Vieter supports a basic build system that allows you to build the packages Vieter supports a basic build system that allows you to build the packages
defined using the Git repositories API by running `vieter build`. For defined using the Git repositories API by running `vieter build`. For
configuration, see [here](/configuration#builder). configuration, see [here](/configuration#).
## How it works ## How it works

View File

@ -23,49 +23,49 @@ with `_FILE`. This for example allows you to provide the API key from a docker
secrets file. secrets file.
{{< /hint >}} {{< /hint >}}
## Modes ## Components
The vieter binary can run in several "modes", indicated by the first argument The vieter binary consists of various componeents, indicated by the first
passed to them. Each mode requires a different configuration. argument passed to them. Each component requires a different configuration.
### Server ### Server
* `log_level`: defines how much logs to show. Valid values are one of `FATAL`, * `log_level`: Which levels of logs to show. Valid values are one of `FATAL`,
`ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN` `ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN`.
* `log_file`: log file to write logs to. Defaults to `vieter.log` in the
current directory.
* `pkg_dir`: where Vieter should store the actual package archives. * `pkg_dir`: where Vieter should store the actual package archives.
* `data_dir`: where Vieter stores the repositories, log file & database. * `data_dir`: where Vieter stores the repositories, log file & database.
* `api_key`: the API key to use when authenticating requests. * `api_key`: the API key to use when authenticating requests.
* `default_arch`: architecture to always add packages of arch `any` to. * `default_arch`: this setting has several uses:
* Packages with architecture `any` will always get added to this
### Builder architecture inside a repository.
* If a package with architecture `any` is the first package to be added to
* `api_key`: the API key to use when authenticating requests. a repository, it'll be added to this architecture.
* `address`: Base your URL of your Vieter instance, e.g. https://example.com * A Git repository added using the API or CLI that doesn't specify an
* `base_image`: image to use when building a package. It should be an Archlinux architecture will use this value as their default.
image. The default if not configured is `archlinux:base-devel`, but this
image only supports arm64. If you require aarch64 support as well, consider
using
[`menci/archlinuxarm:base-devel`](https://hub.docker.com/r/menci/archlinuxarm)
([GH](https://github.com/Menci/docker-archlinuxarm))
### Repos
* `api_key`: the API key to use when authenticating requests.
* `address`: Base your URL of your Vieter instance, e.g. https://example.com
### Cron ### Cron
* `log_level`: defines how much logs to show. Valid values are one of `FATAL`, * `log_level`: defines how much logs to show. Valid values are one of `FATAL`,
`ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN` `ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN`
* `api_key`: the API key to use when authenticating requests.
* `address`: Base your URL of your Vieter instance, e.g. https://example.com. * `address`: Base your URL of your Vieter instance, e.g. https://example.com.
This *must* be the publicly facing URL of your Vieter instance. This *must* be the publicly facing URL of your Vieter instance.
* `api_key`: the API key to use when authenticating requests.
* `data_dir`: where Vieter stores the log file. * `data_dir`: where Vieter stores the log file.
* `base_image`: Docker image from which to create the builder images. * `base_image`: Docker image from which to create the builder images. This
* `max_concurrent_builds`: amount of builds to run at once. image should be for the same Pacman-based distribution as the one you're
* `api_update_frequency`: how frequenty to check for changes in the repo list. installing the packages on. The default if not configured is
* `image_rebuild+frequency`: how frequently to rebuild the builder image `archlinux:base-devel`. Note that this image only supports `x86_64`, so if you
require e.g. `aarch64` support as well you should use a multi-arch image, such
as
[`menci/archlinuxarm:base-devel`](https://hub.docker.com/r/menci/archlinuxarm)
([GH](https://github.com/Menci/docker-archlinuxarm)).
* `max_concurrent_builds`: how many builds to run at once.
* `api_update_frequency`: how frequently to check for changes in the repo list.
* `image_rebuild_frequency`: how frequently to rebuild the builder image.
* `global_schedule`: cron schedule to use for any repo without an individual * `global_schedule`: cron schedule to use for any repo without an individual
schedule schedule.
### Repos CLI
* `address`: Base your URL of your Vieter instance, e.g. https://example.com
* `api_key`: the API key to use when authenticating requests.

View File

@ -49,19 +49,31 @@ For more information about configuring the binary, check out the
Because the project is still in heavy development, it might be useful to build Because the project is still in heavy development, it might be useful to build
from source instead. Luckily, this process is very easy. You'll need make, from source instead. Luckily, this process is very easy. You'll need make,
libarchive & openssl; all of which should be present on an every-day Arch libarchive, sqlite & openssl; all of which should be present on an every-day
install. Then, after cloning the repository, you can use the following commands: Arch install.
If you already have an installation of V on your system, all you have to run is:
```sh ```sh
# Builds the compiler; should usually only be ran once. Vieter compiles using
# the default compiler, but I maintain my own mirror to ensure nothing breaks
# without me knowing.
make v
# Build vieter
# Alternatively, use `make prod` to build the production build.
make make
``` ```
However, because V evolves so rapidly it is possible that Vieter temporarily
doesn't compile using the newest version of V. Because of this, I maintain a
mirror of V which is guaranteed to work with the latest verson of Vieter. To
use my mirror instead of your system:
```sh
# Clone & build my V mirror
make v
# The V_PATH variable tells the Makefile to use a different V binary.
V_PATH=v/v make
```
If you wish to build the production build, use `make prod` instead of `make` in
the above explanation.
{{< hint info >}} {{< hint info >}}
**Note** **Note**
My version of the V compiler is also available on my Vieter instance, My version of the V compiler is also available on my Vieter instance,

View File

@ -0,0 +1,17 @@
# Usage
Vieter is distributed as a swiss army knife-style binary, meaning all of its
components are compiled into a single binary. These various components can then
be used by passing the correct CLI arguments to the binary.
Each of these components requires some configuration variables, a thorough
explanation of this can be found over at the [Configuration](/configuration)
page.
## Components
Currently, the binary consists of the following components:
* [Server](server)
* [Cron](cron)
* [Repos CLI](repos-cli)

View File

@ -0,0 +1,50 @@
---
weight: 10
---
# Server
The server is the implementation of the repository.
```sh
vieter server
```
starts the HTTP server. Its endpoints are listed [here](/api).
## Multiple repositories
Vieter can contain multiple repositories, each of which is further divided into
various architectures.
A repository is created once a package archive is published to it using [this
route](/api#post-repopublish):
```sh
curl -XPOST -H "X-API-KEY: your-key" -T some-package.pkg.tar.zst https://example.com/somerepo/publish
```
This repository can then be added to Pacman as
described below.
## Pacman
A Vieter repository can be added to Pacman like any other repository. In your
`/etc/pacman.conf` file, add the following lines:
```
[vieter]
Server = https://example.com/$repo/$arch
SigLevel = Optional
```
Here, you see two important placeholder variables which get replaced by Pacman
when reading the file. `$repo` is replaced by the name within the square
brackets, which in this case would be `vieter`. `$arch` is replaced by the
output of `uname -m`. Because Vieter supports multiple repositories &
architectures per repository, using this notation makes sure you always use the
correct endpoint for fetching files.
I recommend placing this below all other repository entries, as the order
decides which repository gets used if there's ever a naming conflict.