docs: rewrote installation page

hash-on-upload
Jef Roosens 2022-06-08 22:16:46 +02:00 committed by Jef Roosens
parent 5df5850044
commit 4ecf6a11c4
Signed by: Jef Roosens
GPG Key ID: B580B976584B5F30
4 changed files with 97 additions and 93 deletions

View File

@ -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.

View File

@ -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.

View File

@ -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!

View File

@ -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.