diff --git a/docs/content/_index.md b/docs/content/_index.md index 3a1144b..ecf8138 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -9,12 +9,12 @@ documentation might not be relevant anymore for the latest release. ## Overview -Vieter has a few main features: +Vieter consists of two main parts: -* It's a simple & lightweight implementation of an Arch repository server -* It allows for uploading of built package archives -* It supports a basic build system to periodically re-build packages & upload - them to the server +* A lightweight implementation of an Arch repository, including routes for + uploading built package archives. +* A cron daemon implementation designed to periodically rebuild a given list of + packages, given a Git repository containing their PKGBUILD. {{< hint info >}} **Note** diff --git a/docs/content/api.md b/docs/content/api.md index 7c395eb..b98e7a2 100644 --- a/docs/content/api.md +++ b/docs/content/api.md @@ -56,7 +56,7 @@ Vieter only supports uploading archives compressed using either gzip, zstd or xz at the moment. {{< /hint >}} -## API +## Repos API All API routes require the API key to provided using the `X-Api-Key` header. 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. -### `POST /api/repos?&&&` +### `POST /api/repos?&&` Adds a new Git repository with the provided URL, Git branch & comma-separated list of architectures. @@ -78,7 +78,7 @@ list of architectures. Deletes the Git repository with the provided ID. -### `PATCH /api/repos/?&&&` +### `PATCH /api/repos/?&&&&` Updates the provided parameters for the repo with the given ID. All arguments are optional. diff --git a/docs/content/builder.md b/docs/content/building-packages.md similarity index 97% rename from docs/content/builder.md rename to docs/content/building-packages.md index 6a1bc3a..9322ef2 100644 --- a/docs/content/builder.md +++ b/docs/content/building-packages.md @@ -1,8 +1,8 @@ -# Builder +# Building 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 -configuration, see [here](/configuration#builder). +configuration, see [here](/configuration#). ## How it works diff --git a/docs/content/configuration.md b/docs/content/configuration.md index ded40cb..6ab7940 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -23,49 +23,49 @@ with `_FILE`. This for example allows you to provide the API key from a docker secrets file. {{< /hint >}} -## Modes +## Components -The vieter binary can run in several "modes", indicated by the first argument -passed to them. Each mode requires a different configuration. +The vieter binary consists of various componeents, indicated by the first +argument passed to them. Each component requires a different configuration. ### Server -* `log_level`: defines how much logs to show. Valid values are one of `FATAL`, - `ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN` -* `log_file`: log file to write logs to. Defaults to `vieter.log` in the - current directory. +* `log_level`: Which levels of logs to show. Valid values are one of `FATAL`, + `ERROR`, `WARN`, `INFO` or `DEBUG`. Defaults to `WARN`. * `pkg_dir`: where Vieter should store the actual package archives. * `data_dir`: where Vieter stores the repositories, log file & database. * `api_key`: the API key to use when authenticating requests. -* `default_arch`: architecture to always add packages of arch `any` to. - -### Builder - -* `api_key`: the API key to use when authenticating requests. -* `address`: Base your URL of your Vieter instance, e.g. https://example.com -* `base_image`: image to use when building a package. It should be an Archlinux - 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 +* `default_arch`: this setting has several uses: + * Packages with architecture `any` will always get added to this + architecture inside a repository. + * If a package with architecture `any` is the first package to be added to + a repository, it'll be added to this architecture. + * A Git repository added using the API or CLI that doesn't specify an + architecture will use this value as their default. ### Cron * `log_level`: defines how much logs to show. Valid values are one of `FATAL`, `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. 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. -* `base_image`: Docker image from which to create the builder images. -* `max_concurrent_builds`: amount of builds to run at once. -* `api_update_frequency`: how frequenty to check for changes in the repo list. -* `image_rebuild+frequency`: how frequently to rebuild the builder image +* `base_image`: Docker image from which to create the builder images. This + image should be for the same Pacman-based distribution as the one you're + installing the packages on. The default if not configured is + `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 - 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. diff --git a/docs/content/installation.md b/docs/content/installation.md index 17d3874..e897f28 100644 --- a/docs/content/installation.md +++ b/docs/content/installation.md @@ -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 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 -install. Then, after cloning the repository, you can use the following commands: +libarchive, sqlite & openssl; all of which should be present on an every-day +Arch install. + +If you already have an installation of V on your system, all you have to run is: ```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 ``` + +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 >}} **Note** My version of the V compiler is also available on my Vieter instance, diff --git a/docs/content/usage/_index.md b/docs/content/usage/_index.md new file mode 100644 index 0000000..26d4e29 --- /dev/null +++ b/docs/content/usage/_index.md @@ -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) diff --git a/docs/content/usage/server.md b/docs/content/usage/server.md new file mode 100644 index 0000000..9ae6335 --- /dev/null +++ b/docs/content/usage/server.md @@ -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. + diff --git a/docs/content/usage.md b/docs/content/usage/usage.md similarity index 100% rename from docs/content/usage.md rename to docs/content/usage/usage.md