From a9ddfd8ec8d9d76ea2f45e15bec643538ed13c76 Mon Sep 17 00:00:00 2001 From: Chewing_Bever Date: Thu, 9 Jun 2022 16:26:53 +0200 Subject: [PATCH] docs: too many changes to count --- docs/config.toml | 2 +- docs/content/configuration.md | 78 ++++++++++++++----- .../usage/{builds.md => builds/_index.md} | 2 +- docs/content/usage/builds/schedule.md | 42 ++++++++++ docs/content/usage/repository.md | 12 +-- 5 files changed, 109 insertions(+), 27 deletions(-) rename docs/content/usage/{builds.md => builds/_index.md} (95%) create mode 100644 docs/content/usage/builds/schedule.md diff --git a/docs/config.toml b/docs/config.toml index d0eecb2..5c82044 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -1,7 +1,7 @@ # hugo server --minify --themesDir ... --baseURL=http://0.0.0.0:1313/theme/hugo-book/ baseURL = 'https://rustybever.be/docs/vieter/' -title = 'The Rusty Bever - Docs' +title = 'Vieter - Docs' theme = 'hugo-book' # Book configuration diff --git a/docs/content/configuration.md b/docs/content/configuration.md index ded40cb..27eb213 100644 --- a/docs/content/configuration.md +++ b/docs/content/configuration.md @@ -3,7 +3,7 @@ weight: 20 --- # Configuration -All vieter operations by default try to read in the TOML file `~/.vieterrc` for +By default, all vieter commands try to read in the TOML file `~/.vieterrc` for configuration. The location of this file can be changed by using the `-f` flag. If the above file doesn't exist or you wish to override some of its settings, @@ -19,38 +19,78 @@ the value in the environment variable is used. {{< hint info >}} **Note** All environment variables can also be provided from a file by appending them -with `_FILE`. This for example allows you to provide the API key from a docker +with `_FILE`. This for example allows you to provide the API key from a Docker secrets file. {{< /hint >}} -## Modes +## Commands -The vieter binary can run in several "modes", indicated by the first argument -passed to them. Each mode requires a different configuration. +The first argument passed to Vieter determines which command you wish to use. +Each of these can contain subcommands (e.g. `vieter repos list`), but all +subcommands will use the same configuration. Below you can find the +configuration variable required for each command. -### Server +### `vieter 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`: log verbosity level. Value should be one of `FATAL`, `ERROR`, + `WARN`, `INFO` or `DEBUG`. + * Default: `WARN` +* `log_file`: log file to write logs to. + * Default: `vieter.log` (in the current directory) * `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. +* `default_arch`: this setting serves two main purposes: + * Packages with architecture `any` are always added to this architecture. + This prevents the server from being confused when an `any` package is + published as the very first package for a repository. + * Git repositories added without an `arch` value use this value instead. -### Builder + +### `vieter repos` * `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)) +* `base_image`: image to use when building a package using `vieter repos + build`. + * Default: `archlinux:base-devel` -### Repos +### `vieter cron` + +* `log_level`: log verbosity level. Value should be one of `FATAL`, `ERROR`, + `WARN`, `INFO` or `DEBUG`. + * Default: `WARN` +* `log_file`: log file to write logs to. + * Default: `vieter.log` (in `data_dir`) +* `address`: *public* URL of the Vieter repository server to build for. From + this server the list of Git repositories is retrieved. All built packages are + published to this server. +* `api_key`: API key of the above server. +* `data_dir`: directory to store log file in. +* `base_image`: Docker image to use when building a package. Any Pacman-based + distro image should work, as long as `/etc/pacman.conf` is used & + `base-devel` exists in the repositories. Make sure that the image supports + the architecture of your cron daemon. + * Default: `archlinux:base-devel` (only works on `x86_64`). If you require + `aarch64` support, consider using + [`menci/archlinuxarm:base-devel`](https://hub.docker.com/r/menci/archlinuxarm) + ([GitHub](https://github.com/Menci/docker-archlinuxarm)). This is the image + used for the Vieter CI builds. +* `max_concurrent_builds`: how many builds to run at the same time. + * Default: `1` +* `api_update_frequency`: how frequently (in minutes) to poll the Vieter + repository server for a new list of Git repositories to build. + * Default: `15` +* `image_rebuild_frequency`: Vieter periodically builds a builder image using + the configured base image. This makes sure build containers do not have to + download a lot of packages when updating their system. This setting defines + how frequently (in minutes) to rebuild this builder image. + * Default: `1440` (every 24 hours) +* `global_schedule`: build schedule for any Git repository that does not have a + schedule defined. + * Default: `0 3` (3AM every night) + +### `vieter logs` * `api_key`: the API key to use when authenticating requests. * `address`: Base your URL of your Vieter instance, e.g. https://example.com diff --git a/docs/content/usage/builds.md b/docs/content/usage/builds/_index.md similarity index 95% rename from docs/content/usage/builds.md rename to docs/content/usage/builds/_index.md index db11bec..c6f0603 100644 --- a/docs/content/usage/builds.md +++ b/docs/content/usage/builds/_index.md @@ -24,7 +24,7 @@ vieter repos add some-url some-branch some-repository ``` Here, `some-url` is the URL of the Git repository containing the PKGBUILD. This -URL is passed to `git clone`, so the repository should be public. Vieter +URL is passed to `git clone`, meaning the repository should be public. Vieter expects the same format as an AUR Git repository, so you can directly use AUR URLs here. diff --git a/docs/content/usage/builds/schedule.md b/docs/content/usage/builds/schedule.md new file mode 100644 index 0000000..38f76a4 --- /dev/null +++ b/docs/content/usage/builds/schedule.md @@ -0,0 +1,42 @@ +# Cron schedule syntax + +The Vieter cron daemon uses a subset of the cron expression syntax to schedule +builds. + +## Format + +`a b c d` + +* `a`: minutes +* `b`: hours +* `c`: days +* `d`: months + +An expression consists of two to four sections. If less than four sections are +provided, the parser will append `*` until there are four sections. This means +that `0 3` is the same as `0 3 * *`. + +Each section consists of one or more parts, separated by a comma. Each of these +parts, in turn, can be one of the following (any letters are integers): + +* `*`: allow all possible values. +* `a`: only this value is allowed. +* `*/n`: allow every n-th value. +* `a/n`: allow every n-th value, starting at a in the list. +* `a-b`: allow every value between a and b, bounds included. +* `a-b/n`: allow every n-th value inside the list of values between a and b, + bounds included. + +Each section can consist of as many of these parts as necessary. + +## Examples + +* `0 3`: every day at 03:00AM. +* `0 0 */7`: every 7th day of the month, at midnight. + +## CLI tool + +The Vieter binary contains a command that shows you the next matching times for +a given expression. This can be useful to understand the syntax. For more +information, see +[vieter-schedule(1)](https://rustybever.be/man/vieter/vieter-schedule.1.html). diff --git a/docs/content/usage/repository.md b/docs/content/usage/repository.md index 1dc6bc6..3ddd2fc 100644 --- a/docs/content/usage/repository.md +++ b/docs/content/usage/repository.md @@ -20,12 +20,12 @@ Server = https://example.com/$repo/$arch SigLevel = Optional ``` -Here, `$repo` & `$arch` are not variables you have to fill in yourself. Rather, -Pacman will substitute these when reading the config file. `$repo` is replaced -by the name between the square brackets (in this case `repo-name`), & `$arch` -is replaced by your system's architecture, e.g. `x86_64`. Of course, you can -also fill in these values manually yourself, e.g. if you wish to use a -different name inside the square brackets. +Here, `$repo` and `$arch` are not variables you have to fill in yourself. +Rather, Pacman will substitute these when reading the config file. `$repo` is +replaced by the name between the square brackets (in this case `repo-name`), +and `$arch` is replaced by your system's architecture, e.g. `x86_64`. Of +course, you can also fill in these values manually yourself, e.g. if you wish +to use a different name inside the square brackets. Important to note is that, when two repositories contain a package with the same name, Pacman will choose the one from the repository that's highest up in