From 4ecf6a11c4518f01854fbace08ce33db382a732b Mon Sep 17 00:00:00 2001 From: Chewing_Bever Date: Wed, 8 Jun 2022 22:16:46 +0200 Subject: [PATCH] docs: rewrote installation page --- README.md | 37 +++++----- docs/config.toml | 7 +- docs/content/_index.md | 15 ++-- docs/content/installation.md | 131 +++++++++++++++++++---------------- 4 files changed, 97 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 34e6fd3a..892396a2 100644 --- a/README.md +++ b/README.md @@ -22,13 +22,6 @@ a while now. I wanted a fast language that I could code while relaxing, without having to exert too much mental effort & V seemed like the right choice for that. -### Compiler - -Vieter compiles with the standard Vlang compiler. However, I do maintain a -[mirror](https://git.rustybever.be/Chewing_Bever/v). This is to ensure my CI -does not break without reason, as I control when & how frequently the mirror is -updated to reflect the official repository. - ## Features * Arch repository server @@ -41,20 +34,24 @@ updated to reflect the official repository. ## Building -In order to build Vieter, you'll need a couple of libraries: +Besides a V installer, Vieter also requires the following libraries to work: -* An installation of V * gc * libarchive * openssl +* sqlite3 -**NOTE**: if you encounter any issues compiling Vieter using the absolute -latest version of V, it might be because my mirror is missing a specific commit -that causes issues. For this reason, the `make v` command exists which will -clone my compiler in the `v` directory & build it. Afterwards, you can use this -compiler with make by prepending all make commands with `V_PATH=v/v`. If you do -encounter this issue, please let me know so I can update my mirror & the -codebase to fix it! +### Compiler + +Vieter compiles with the standard Vlang compiler. However, I do maintain a +[mirror](https://git.rustybever.be/vieter/v). This is to ensure my CI does not +break without reason, as I control when & how frequently the mirror is updated +to reflect the official repository. + +If you encounter issues using the latest V compiler, try using my mirror +instead. `make v` will clone the repository & build the mirror. Afterwards, +prepending any make command with `V_PATH=v/v` tells make to use the locally +compiled mirror instead. ## Contributing @@ -70,7 +67,7 @@ If you wish to contribute to the project, please take note of the following: The `docs` directory contains a Hugo site consisting of all user & administrator documentation. `docs/api` on the other hand is a -[slate](https://github.com/slatedocs/slate) project describing the HTTP web +[Slate](https://github.com/slatedocs/slate) project describing the HTTP web API. To modify the Hugo documentation, you'll need to install Hugo. Afterwards, you @@ -81,8 +78,8 @@ can use the following commands inside the `docs` directory: hugo # Host an auto-refreshing web server with the documentation. Important to note -is that the files will be at `http://localhost:1313/docs/vieter` instead of -just `http://localhost:1313/docs/vieter` +# is that the files will be at `http://localhost:1313/docs/vieter` instead of +# just `http://localhost:1313/` hugo server ``` @@ -96,6 +93,6 @@ docker run \ -v $(pwd)/docs/api/source:/srv/slate/source slatedocs/slate serve ``` -This'll make the slate docs available at http://localhost:4567. Sadly, this +This will make the Slate docs available at http://localhost:4567. Sadly, this server doesn't auto-refresh, so you'll have to manually refresh your browser every time you make a change. diff --git a/docs/config.toml b/docs/config.toml index 5b0f20f4..61aa3ae2 100644 --- a/docs/config.toml +++ b/docs/config.toml @@ -6,7 +6,8 @@ theme = 'hugo-book' # Book configuration disablePathToLower = true -enableGitInfo = true +# Doesn't work with docs as subdir +enableGitInfo = false # Needed for mermaid/katex shortcodes [markup] @@ -29,7 +30,7 @@ enableGitInfo = true [menu] [[menu.after]] name = "API Documentation" - url = "https://rustybever.be/docs/vieter/api" + url = "https://rustybever.be/docs/vieter/api/" weight = 10 [[menu.after]] name = "Man Pages" @@ -69,7 +70,7 @@ enableGitInfo = true # Set source repository location. # Used for 'Last Modified' and 'Edit this page' links. - BookRepo = 'https://git.rustybever.be/Chewing_Bever/docs' + BookRepo = 'https://git.rustybever.be/vieter/vieter/docs' # (Optional, default 'commit') Specifies commit portion of the link to the page's last modified # commit hash for 'doc' page type. diff --git a/docs/content/_index.md b/docs/content/_index.md index 3a1144ba..efcdf6d5 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -9,12 +9,9 @@ documentation might not be relevant anymore for the latest release. ## Overview -Vieter has a few main features: - -* 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 +Vieter consists of two main parts, namely an implementation of an Arch +repository server & a scheduling system to periodically build Pacman packages & +publish them to a repository. {{< hint info >}} **Note** @@ -26,12 +23,12 @@ well. ### Why? -Vieter is my personal solution for a problem I've been facing for months: +Vieter is my personal solution to a problem I've been facing for months: extremely long AUR package build times. I run EndeavourOS on both my laptops, one of which being a rather old MacBook Air. I really like being a beta-tester for projects & run development builds for multiple packages (nheko, -newsflash...). The issue with this is that I have to regularly re-build these -packages in order to stay up to date with development & these builds can take a +newsflash...). Because of this, I have to regularly re-build these packages in +order to stay up to date with development. However, these builds can take a really long time on the old MacBook. This project is a solution to that problem: instead of building the packages locally, I can build them automatically in the cloud & just download them whenever I update my system! diff --git a/docs/content/installation.md b/docs/content/installation.md index 17d3874c..5cc7a0ee 100644 --- a/docs/content/installation.md +++ b/docs/content/installation.md @@ -3,76 +3,85 @@ weight: 10 --- # Installation +Vieter consists of a single binary, akin to busybox. The binary's behavior is +determined by its CLI arguments, e.g. `vieter server` starts the repository +server. + +All installation solutions can be configured the same way, +as described [here](/configuration). + ## Docker -Docker is the recommended way to install vieter. The images can be pulled from -[`chewingbever/vieter`](https://hub.docker.com/r/chewingbever/vieter). You can -either pull a release tag (e.g. `chewingbever/vieter:0.1.0-rc1`), or pull the -`chewingbever/vieter:dev` tag. The latter is updated every time a new commit is -pushed to the development branch. This branch will be the most up to date, but -does not give any guarantees about stability, so beware! +Docker images are published to the +[`chewingbever/vieter`](https://hub.docker.com/r/chewingbever/vieter) Docker +Hub repository. You can either pull a release tag (e.g. +`chewingbever/vieter:0.1.0-rc1`), or pull the `chewingbever/vieter:dev` tag. +The latter is updated every time a new commit is pushed to the development +branch. This branch will be the most up to date, but does not give any +guarantees about stability, so beware! -The simplest way to run the Docker image is using a plain Docker command: +Due to the single-binary design of Vieter, this image can be used both for the +repository server & the cron daemon. -```sh -docker run \ - --rm \ - -d \ - -v /path/to/data:/data \ - -e VIETER_API_KEY=changeme \ - -e VIETER_DEFAULT_ARCH=x86_64 \ - -p 8000:8000 \ - chewingbever/vieter:dev +Below is an example compose file to set up both the repository server & the +cron daemon: + +```yaml +version: '3' + +services: + server: + image: 'chewingbever/vieter:dev' + restart: 'always' + + environment: + - 'VIETER_API_KEY=secret' + - 'VIETER_DEFAULT_ARCH=x86_64' + volumes: + - 'data:/data' + + cron: + image: 'chewingbever/vieter:dev' + restart: 'always' + user: root + command: 'vieter cron' + + environment: + - 'VIETER_API_KEY=secret' + # MUST be public URL of Vieter repository + - 'VIETER_ADDRESS=https://example.com' + - 'VIETER_DEFAULT_ARCH=x86_64' + - 'VIETER_MAX_CONCURRENT_BUILDS=2' + - 'VIETER_GLOBAL_SCHEDULE=0 3' + +volumes: + data: ``` -Here, you should change `/path/to/data` to the path on your host where you want -vieter to store its files. - -The default configuration will store everything inside the `/data` directory. - -Inside the container, the Vieter server runs on port 8000. This port should be -exposed to the public accordingely. - -For an overview of how to configure vieter & which environment variables can be -used, see the [Configuration](/configuration) page. - ## Binary -On the [releases](https://git.rustybever.be/Chewing_Bever/vieter/releases) -page, you can find statically compiled binaries for all released versions. You -can download the binary for your host's architecture & run it that way. +On the +[releases](https://git.rustybever.be/vieter/vieter/releases) +page, you can find statically compiled binaries for all +released versions. This is the same binary as used inside +the Docker images. -For more information about configuring the binary, check out the -[Configuration](/configuration) page. +## Arch + +I publish both development & release versions of Vieter to my personal +repository, https://arch.r8r.be. Packages are available for `x86_64` & +`aarch64`. To use the repository, add the following to your `pacman.conf`: + +``` +[vieter] +Server = https://arch.r8r.be/$repo/$arch +SigLevel = Optional +``` + +Afterwards, you can update your system & install the `vieter` package for the +latest official release or `vieter-git` for the latest development release. ## Building from source -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: - -```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 -``` -{{< hint info >}} -**Note** -My version of the V compiler is also available on my Vieter instance, -https://arch.r8r.be. It's in the `vieter` repository, with the package being -named `vieter-v`. The compiler is available for both x86_64 & aarch64. -{{< /hint >}} - -## My Vieter instance - -Besides uploading development Docker images, my CI also publishes x86_64 & -aarch64 packages to my personal Vieter instance, https://arch.r8r.be. If you'd -like, you can use this repository as well by adding it to your Pacman -configuration as described [here](/usage#configuring-pacman). Both the -repository & the package are called `vieter`. +The project [README](https://git.rustybever.be/vieter/vieter#building) contains +instructions for building Vieter from source.