arcanis/ahriman
1
0
Fork 0
mirror of https://github.com/arcan1s/ahriman.git synced 2025-04-28 17:27:17 +00:00
Code Issues Projects Releases Wiki Activity

fix docs according to the generated htmls

Browse Source
This commit is contained in:
Evgenii Alekseev 2022-05-05 20:08:02 +03:00
parent 6671e61120
commit a5a7432c62
17 changed files with 3787 additions and 4715 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.readthedocs.yaml
View File

@ -9,7 +9,7 @@ build:
sphinx: sphinx:
builder: html builder: html
configuration: docs/source/conf.py configuration: docs/conf.py
python: python:
install: install:

4
Makefile
View File

@ -42,8 +42,8 @@ push: spec archlinux
spec: spec:
# make sure that old files are removed # make sure that old files are removed
find docs/source -type f -name "$(PROJECT)*.rst" -delete find docs -type f -name "$(PROJECT)*.rst" -delete
rm -f docs/source/modules.rst rm -f docs/modules.rst
tox -e docs tox -e docs
spec-html: spec spec-html: spec

6
README.md
View File

@ -23,10 +23,10 @@ Wrapper for managing custom repository inspired by [repo-scripts](https://github
## Installation and run ## Installation and run
For installation details please refer to the [documentation](docs/setup.md). For command help, `--help` subcommand must be used. Subcommands have own help message as well. The package also provides a [man page](docs/ahriman.1). For installation details please refer to the [documentation](docs/setup.rst). For command help, `--help` subcommand must be used. Subcommands have own help message as well. The package also provides a [man page](docs/ahriman.1).
## Configuration ## Configuration
Every available option is described in the [documentation](docs/configuration.md). Every available option is described in the [documentation](docs/configuration.rst).
## [FAQ](docs/faq.md) ## [FAQ](docs/faq.rst)

43
docs/advanced-usage.rst Normal file
View File

@ -0,0 +1,43 @@
Advanced usage
==============
Depending on the goal the package can be used in different ways. Nevertheless, in the most cases you will need some basic classes
.. code-block:: python
from pathlib import Path
from ahriman.core.configuration import Configuration
from ahriman.core.database.sqlite import SQLite
architecture = "x86_64"
configuration = Configuration.from_path(Path("/etc/ahriman.ini"), architecture, quiet=False)
sqlite = SQLite.load(configuration)
At this point there are ``configuration`` and ``database`` instances which can be used later at any time anywhere, e.g.
.. code-block:: python
# instance of ``RepositoryPaths`` class
paths = configuration.repository_paths
Almost all actions are wrapped by ``ahriman.core.repository.Repository`` class
.. code-block:: python
from ahriman.core.repository import Repository
repository = Repository(architecture, configuration, database, no_report=False, unsafe=False)
And the ``repository`` instance can be used to perform repository maintenance
.. code-block:: python
build_result = repository.process_build(known_packages)
built_packages = repository.packages_built()
update_result = repository.process_update(built_packages)
repository.process_report(None, update_result)
repository.process_sync(None, update_result.success)
For the more info please refer to the classes documentation.

7096
docs/ahriman-architecture.svg
View File

File diff suppressed because it is too large Load Diff
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 540 KiB

After

Width:  |  Height:  |  Size: 570 KiB

546
docs/ahriman.1
View File

@ -1,4 +1,4 @@
.TH ahriman "1" Manual .TH AHRIMAN "1" Manual
.SH NAME .SH NAME
ahriman ahriman
.SH SYNOPSIS .SH SYNOPSIS
@ -6,8 +6,8 @@ ahriman
[-h] [-a ARCHITECTURE] [-c CONFIGURATION] [--force] [-l LOCK] [--no-report] [-q] [--unsafe] [-v] {aur-search,search,help,help-commands-unsafe,key-import,package-add,add,package-update,package-remove,remove,package-status,status,package-status-remove,package-status-update,status-update,patch-add,patch-list,patch-remove,repo-backup,repo-check,check,repo-clean,clean,repo-config,config,repo-rebuild,rebuild,repo-remove-unknown,remove-unknown,repo-report,report,repo-restore,repo-setup,init,repo-init,setup,repo-sign,sign,repo-status-update,repo-sync,sync,repo-update,update,user-add,user-list,user-remove,web} ... [-h] [-a ARCHITECTURE] [-c CONFIGURATION] [--force] [-l LOCK] [--no-report] [-q] [--unsafe] [-v] {aur-search,search,help,help-commands-unsafe,key-import,package-add,add,package-update,package-remove,remove,package-status,status,package-status-remove,package-status-update,status-update,patch-add,patch-list,patch-remove,repo-backup,repo-check,check,repo-clean,clean,repo-config,config,repo-rebuild,rebuild,repo-remove-unknown,remove-unknown,repo-report,report,repo-restore,repo-setup,init,repo-init,setup,repo-sign,sign,repo-status-update,repo-sync,sync,repo-update,update,user-add,user-list,user-remove,web} ...
.SH DESCRIPTION .SH DESCRIPTION
ArcH Linux ReposItory MANager ArcH Linux ReposItory MANager
.SH OPTIONS
.SH OPTIONS
.TP .TP
\fB\-a\fR \fI\,ARCHITECTURE\/\fR, \fB\-\-architecture\fR \fI\,ARCHITECTURE\/\fR \fB\-a\fR \fI\,ARCHITECTURE\/\fR, \fB\-\-architecture\fR \fI\,ARCHITECTURE\/\fR
target architectures (can be used multiple times) target architectures (can be used multiple times)
@ -40,8 +40,8 @@ allow to run ahriman as non\-ahriman user. Some actions might be unavailable
\fB\-v\fR, \fB\-\-version\fR \fB\-v\fR, \fB\-\-version\fR
show program's version number and exit show program's version number and exit
.SS .SH
\fBSub-commands\fR COMMAND
.TP .TP
\fBahriman\fR \fI\,aur-search\/\fR \fBahriman\fR \fI\,aur-search\/\fR
search for package search for package
@ -129,9 +129,9 @@ remove user
.TP .TP
\fBahriman\fR \fI\,web\/\fR \fBahriman\fR \fI\,web\/\fR
web server web server
.SH OPTIONS 'ahriman aur-search' .SH COMMAND \fI\,'ahriman aur-search'\/\fR
usage: ahriman aur-search [-h] [-e] [-i] usage: ahriman aur-search [-h] [-e] [-i]
[--sort-by {description,first_submitted,id,last_modified,maintainer,name,num_votes,out_of_date,package_base,package_base_id,popularity,url,url_path,version}] [--sort-by {description,first_submitted,id,last_modified,maintainer,name,num_votes,out_of_date,package_base,package_base_id,popularity,repository,url,url_path,version}]
search [search ...] search [search ...]
search for package in AUR using API search for package in AUR using API
@ -140,6 +140,7 @@ search for package in AUR using API
\fBsearch\fR \fBsearch\fR
search terms, can be specified multiple times, result will match all terms search terms, can be specified multiple times, result will match all terms
.SH OPTIONS \fI\,'ahriman aur-search'\/\fR
.TP .TP
\fB\-e\fR, \fB\-\-exit\-code\fR \fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty return non\-zero exit status if result is empty
@ -149,35 +150,11 @@ return non\-zero exit status if result is empty
show additional package information show additional package information
.TP .TP
\fB\-\-sort\-by\fR {description,first_submitted,id,last_modified,maintainer,name,num_votes,out_of_date,package_base,package_base_id,popularity,url,url_path,version} \fB\-\-sort\-by\fR \fI\,{description,first_submitted,id,last_modified,maintainer,name,num_votes,out_of_date,package_base,package_base_id,popularity,repository,url,url_path,version}\/\fR
sort field by this field. In case if two packages have the same value of the specified field, they will be always sorted sort field by this field. In case if two packages have the same value of the specified field, they will be always sorted
by name by name
.SH OPTIONS 'ahriman search' .SH COMMAND \fI\,'ahriman help'\/\fR
usage: ahriman aur-search [-h] [-e] [-i]
[--sort-by {description,first_submitted,id,last_modified,maintainer,name,num_votes,out_of_date,package_base,package_base_id,popularity,url,url_path,version}]
search [search ...]
search for package in AUR using API
.TP
\fBsearch\fR
search terms, can be specified multiple times, result will match all terms
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.TP
\fB\-i\fR, \fB\-\-info\fR
show additional package information
.TP
\fB\-\-sort\-by\fR {description,first_submitted,id,last_modified,maintainer,name,num_votes,out_of_date,package_base,package_base_id,popularity,url,url_path,version}
sort field by this field. In case if two packages have the same value of the specified field, they will be always sorted
by name
.SH OPTIONS 'ahriman help'
usage: ahriman help [-h] [command] usage: ahriman help [-h] [command]
show help message for application or command and exit show help message for application or command and exit
@ -186,19 +163,18 @@ show help message for application or command and exit
\fBcommand\fR \fBcommand\fR
show help message for specific command show help message for specific command
.SH COMMAND \fI\,'ahriman help-commands-unsafe'\/\fR
.SH OPTIONS 'ahriman help-commands-unsafe'
usage: ahriman help-commands-unsafe [-h] [--command COMMAND] usage: ahriman help-commands-unsafe [-h] [--command COMMAND]
list unsafe commands as defined in default args list unsafe commands as defined in default args
.SH OPTIONS \fI\,'ahriman help-commands-unsafe'\/\fR
.TP .TP
\fB\-\-command\fR \fI\,COMMAND\/\fR \fB\-\-command\fR \fI\,COMMAND\/\fR
instead of showing commands, just test command line for unsafe subcommand and return 0 in case if command is safe and 1 instead of showing commands, just test command line for unsafe subcommand and return 0 in case if command is safe and 1
otherwise otherwise
.SH OPTIONS 'ahriman key-import' .SH COMMAND \fI\,'ahriman key-import'\/\fR
usage: ahriman key-import [-h] [--key-server KEY_SERVER] key usage: ahriman key-import [-h] [--key-server KEY_SERVER] key
import PGP key from public sources to the repository user import PGP key from public sources to the repository user
@ -207,11 +183,12 @@ import PGP key from public sources to the repository user
\fBkey\fR \fBkey\fR
PGP key to import from public server PGP key to import from public server
.SH OPTIONS \fI\,'ahriman key-import'\/\fR
.TP .TP
\fB\-\-key\-server\fR \fI\,KEY_SERVER\/\fR \fB\-\-key\-server\fR \fI\,KEY_SERVER\/\fR
key server for key import key server for key import
.SH OPTIONS 'ahriman package-add' .SH COMMAND \fI\,'ahriman package-add'\/\fR
usage: ahriman package-add [-h] [-e] [-n] usage: ahriman package-add [-h] [-e] [-n]
[-s {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}] [-s {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}]
[--without-dependencies] [--without-dependencies]
@ -223,6 +200,7 @@ add existing or new package to the build queue
\fBpackage\fR \fBpackage\fR
package source (base name, path to local files, remote URL) package source (base name, path to local files, remote URL)
.SH OPTIONS \fI\,'ahriman package-add'\/\fR
.TP .TP
\fB\-e\fR, \fB\-\-exit\-code\fR \fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty return non\-zero exit status if result is empty
@ -232,70 +210,14 @@ return non\-zero exit status if result is empty
run update function after run update function after
.TP .TP
\fB\-s\fR {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}, \fB\-\-source\fR {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository} \fB\-s\fR \fI\,{PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}\/\fR, \fB\-\-source\fR \fI\,{PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}\/\fR
explicitly specify the package source for this command explicitly specify the package source for this command
.TP .TP
\fB\-\-without\-dependencies\fR \fB\-\-without\-dependencies\fR
do not add dependencies do not add dependencies
.SH OPTIONS 'ahriman add' .SH COMMAND \fI\,'ahriman package-remove'\/\fR
usage: ahriman package-add [-h] [-e] [-n]
[-s {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}]
[--without-dependencies]
package [package ...]
add existing or new package to the build queue
.TP
\fBpackage\fR
package source (base name, path to local files, remote URL)
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.TP
\fB\-n\fR, \fB\-\-now\fR
run update function after
.TP
\fB\-s\fR {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}, \fB\-\-source\fR {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}
explicitly specify the package source for this command
.TP
\fB\-\-without\-dependencies\fR
do not add dependencies
.SH OPTIONS 'ahriman package-update'
usage: ahriman package-add [-h] [-e] [-n]
[-s {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}]
[--without-dependencies]
package [package ...]
add existing or new package to the build queue
.TP
\fBpackage\fR
package source (base name, path to local files, remote URL)
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.TP
\fB\-n\fR, \fB\-\-now\fR
run update function after
.TP
\fB\-s\fR {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}, \fB\-\-source\fR {PackageSource.Auto,PackageSource.Archive,PackageSource.AUR,PackageSource.Directory,PackageSource.Local,PackageSource.Remote,PackageSource.Repository}
explicitly specify the package source for this command
.TP
\fB\-\-without\-dependencies\fR
do not add dependencies
.SH OPTIONS 'ahriman package-remove'
usage: ahriman package-remove [-h] package [package ...] usage: ahriman package-remove [-h] package [package ...]
remove package from the repository remove package from the repository
@ -304,18 +226,7 @@ remove package from the repository
\fBpackage\fR \fBpackage\fR
package name or base package name or base
.SH COMMAND \fI\,'ahriman package-status'\/\fR
.SH OPTIONS 'ahriman remove'
usage: ahriman package-remove [-h] package [package ...]
remove package from the repository
.TP
\fBpackage\fR
package name or base
.SH OPTIONS 'ahriman package-status'
usage: ahriman package-status [-h] [--ahriman] [-e] [-i] usage: ahriman package-status [-h] [--ahriman] [-e] [-i]
[-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}] [-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}]
[package ...] [package ...]
@ -326,6 +237,7 @@ request status of the package
\fBpackage\fR \fBpackage\fR
filter status by package base filter status by package base
.SH OPTIONS \fI\,'ahriman package-status'\/\fR
.TP .TP
\fB\-\-ahriman\fR \fB\-\-ahriman\fR
get service status itself get service status itself
@ -339,37 +251,10 @@ return non\-zero exit status if result is empty
show additional package information show additional package information
.TP .TP
\fB\-s\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}, \fB\-\-status\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success} \fB\-s\fR \fI\,{BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}\/\fR, \fB\-\-status\fR \fI\,{BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}\/\fR
filter packages by status filter packages by status
.SH OPTIONS 'ahriman status' .SH COMMAND \fI\,'ahriman package-status-remove'\/\fR
usage: ahriman package-status [-h] [--ahriman] [-e] [-i]
[-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}]
[package ...]
request status of the package
.TP
\fBpackage\fR
filter status by package base
.TP
\fB\-\-ahriman\fR
get service status itself
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.TP
\fB\-i\fR, \fB\-\-info\fR
show additional package information
.TP
\fB\-s\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}, \fB\-\-status\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}
filter packages by status
.SH OPTIONS 'ahriman package-status-remove'
usage: ahriman package-status-remove [-h] package [package ...] usage: ahriman package-status-remove [-h] package [package ...]
remove the package from the status page remove the package from the status page
@ -378,8 +263,7 @@ remove the package from the status page
\fBpackage\fR \fBpackage\fR
remove specified packages remove specified packages
.SH COMMAND \fI\,'ahriman package-status-update'\/\fR
.SH OPTIONS 'ahriman package-status-update'
usage: ahriman package-status-update [-h] usage: ahriman package-status-update [-h]
[-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}] [-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}]
[package ...] [package ...]
@ -390,26 +274,12 @@ update package status on the status page
\fBpackage\fR \fBpackage\fR
set status for specified packages. If no packages supplied, service status will be updated set status for specified packages. If no packages supplied, service status will be updated
.SH OPTIONS \fI\,'ahriman package-status-update'\/\fR
.TP .TP
\fB\-s\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}, \fB\-\-status\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success} \fB\-s\fR \fI\,{BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}\/\fR, \fB\-\-status\fR \fI\,{BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}\/\fR
new status new status
.SH OPTIONS 'ahriman status-update' .SH COMMAND \fI\,'ahriman patch-add'\/\fR
usage: ahriman package-status-update [-h]
[-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}]
[package ...]
update package status on the status page
.TP
\fBpackage\fR
set status for specified packages. If no packages supplied, service status will be updated
.TP
\fB\-s\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}, \fB\-\-status\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}
new status
.SH OPTIONS 'ahriman patch-add'
usage: ahriman patch-add [-h] [-t TRACK] package usage: ahriman patch-add [-h] [-t TRACK] package
create or update source patches create or update source patches
@ -418,11 +288,12 @@ create or update source patches
\fBpackage\fR \fBpackage\fR
path to directory with changed files for patch addition/update path to directory with changed files for patch addition/update
.SH OPTIONS \fI\,'ahriman patch-add'\/\fR
.TP .TP
\fB\-t\fR \fI\,TRACK\/\fR, \fB\-\-track\fR \fI\,TRACK\/\fR \fB\-t\fR \fI\,TRACK\/\fR, \fB\-\-track\fR \fI\,TRACK\/\fR
files which has to be tracked files which has to be tracked
.SH OPTIONS 'ahriman patch-list' .SH COMMAND \fI\,'ahriman patch-list'\/\fR
usage: ahriman patch-list [-h] [-e] [package] usage: ahriman patch-list [-h] [-e] [package]
list available patches for the package list available patches for the package
@ -431,11 +302,12 @@ list available patches for the package
\fBpackage\fR \fBpackage\fR
package base package base
.SH OPTIONS \fI\,'ahriman patch-list'\/\fR
.TP .TP
\fB\-e\fR, \fB\-\-exit\-code\fR \fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty return non\-zero exit status if result is empty
.SH OPTIONS 'ahriman patch-remove' .SH COMMAND \fI\,'ahriman patch-remove'\/\fR
usage: ahriman patch-remove [-h] package usage: ahriman patch-remove [-h] package
remove patches for the package remove patches for the package
@ -444,8 +316,7 @@ remove patches for the package
\fBpackage\fR \fBpackage\fR
package base package base
.SH COMMAND \fI\,'ahriman repo-backup'\/\fR
.SH OPTIONS 'ahriman repo-backup'
usage: ahriman repo-backup [-h] path usage: ahriman repo-backup [-h] path
backup settings and database backup settings and database
@ -454,8 +325,7 @@ backup settings and database
\fBpath\fR \fBpath\fR
path of the output archive path of the output archive
.SH COMMAND \fI\,'ahriman repo-check'\/\fR
.SH OPTIONS 'ahriman repo-check'
usage: ahriman repo-check [-h] [-e] [--no-vcs] [package ...] usage: ahriman repo-check [-h] [-e] [--no-vcs] [package ...]
check for packages updates. Same as update \-\-dry\-run \-\-no\-manual check for packages updates. Same as update \-\-dry\-run \-\-no\-manual
@ -464,6 +334,7 @@ check for packages updates. Same as update \-\-dry\-run \-\-no\-manual
\fBpackage\fR \fBpackage\fR
filter check by package base filter check by package base
.SH OPTIONS \fI\,'ahriman repo-check'\/\fR
.TP .TP
\fB\-e\fR, \fB\-\-exit\-code\fR \fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty return non\-zero exit status if result is empty
@ -472,29 +343,12 @@ return non\-zero exit status if result is empty
\fB\-\-no\-vcs\fR \fB\-\-no\-vcs\fR
do not check VCS packages do not check VCS packages
.SH OPTIONS 'ahriman check' .SH COMMAND \fI\,'ahriman repo-clean'\/\fR
usage: ahriman repo-check [-h] [-e] [--no-vcs] [package ...]
check for packages updates. Same as update \-\-dry\-run \-\-no\-manual
.TP
\fBpackage\fR
filter check by package base
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.TP
\fB\-\-no\-vcs\fR
do not check VCS packages
.SH OPTIONS 'ahriman repo-clean'
usage: ahriman repo-clean [-h] [--cache] [--chroot] [--manual] [--packages] usage: ahriman repo-clean [-h] [--cache] [--chroot] [--manual] [--packages]
remove local caches remove local caches
.SH OPTIONS \fI\,'ahriman repo-clean'\/\fR
.TP .TP
\fB\-\-cache\fR \fB\-\-cache\fR
clear directory with package caches clear directory with package caches
@ -511,48 +365,17 @@ clear manually added packages queue
\fB\-\-packages\fR \fB\-\-packages\fR
clear directory with built packages clear directory with built packages
.SH OPTIONS 'ahriman clean' .SH COMMAND \fI\,'ahriman repo-config'\/\fR
usage: ahriman repo-clean [-h] [--cache] [--chroot] [--manual] [--packages]
remove local caches
.TP
\fB\-\-cache\fR
clear directory with package caches
.TP
\fB\-\-chroot\fR
clear build chroot
.TP
\fB\-\-manual\fR
clear manually added packages queue
.TP
\fB\-\-packages\fR
clear directory with built packages
.SH OPTIONS 'ahriman repo-config'
usage: ahriman repo-config [-h] usage: ahriman repo-config [-h]
dump configuration for the specified architecture dump configuration for the specified architecture
.SH COMMAND \fI\,'ahriman repo-rebuild'\/\fR
.SH OPTIONS 'ahriman config'
usage: ahriman repo-config [-h]
dump configuration for the specified architecture
.SH OPTIONS 'ahriman repo-rebuild'
usage: ahriman repo-rebuild [-h] [--depends-on DEPENDS_ON] [--dry-run] [--from-database] [-e] usage: ahriman repo-rebuild [-h] [--depends-on DEPENDS_ON] [--dry-run] [--from-database] [-e]
force rebuild whole repository force rebuild whole repository
.SH OPTIONS \fI\,'ahriman repo-rebuild'\/\fR
.TP .TP
\fB\-\-depends\-on\fR \fI\,DEPENDS_ON\/\fR \fB\-\-depends\-on\fR \fI\,DEPENDS_ON\/\fR
only rebuild packages that depend on specified package only rebuild packages that depend on specified package
@ -571,36 +394,12 @@ original ahriman instance run with web service and have run repo\-update at leas
\fB\-e\fR, \fB\-\-exit\-code\fR \fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty return non\-zero exit status if result is empty
.SH OPTIONS 'ahriman rebuild' .SH COMMAND \fI\,'ahriman repo-remove-unknown'\/\fR
usage: ahriman repo-rebuild [-h] [--depends-on DEPENDS_ON] [--dry-run] [--from-database] [-e]
force rebuild whole repository
.TP
\fB\-\-depends\-on\fR \fI\,DEPENDS_ON\/\fR
only rebuild packages that depend on specified package
.TP
\fB\-\-dry\-run\fR
just perform check for packages without rebuild process itself
.TP
\fB\-\-from\-database\fR
read packages from database instead of filesystem. This feature in particular is required in case if you would like to
restore repository from another repository instance. Note however that in order to restore packages you need to have
original ahriman instance run with web service and have run repo\-update at least once.
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.SH OPTIONS 'ahriman repo-remove-unknown'
usage: ahriman repo-remove-unknown [-h] [--dry-run] [-i] usage: ahriman repo-remove-unknown [-h] [--dry-run] [-i]
remove packages which are missing in AUR and do not have local PKGBUILDs remove packages which are missing in AUR and do not have local PKGBUILDs
.SH OPTIONS \fI\,'ahriman repo-remove-unknown'\/\fR
.TP .TP
\fB\-\-dry\-run\fR \fB\-\-dry\-run\fR
just perform check for packages without removal just perform check for packages without removal
@ -609,21 +408,7 @@ just perform check for packages without removal
\fB\-i\fR, \fB\-\-info\fR \fB\-i\fR, \fB\-\-info\fR
show additional package information show additional package information
.SH OPTIONS 'ahriman remove-unknown' .SH COMMAND \fI\,'ahriman repo-report'\/\fR
usage: ahriman repo-remove-unknown [-h] [--dry-run] [-i]
remove packages which are missing in AUR and do not have local PKGBUILDs
.TP
\fB\-\-dry\-run\fR
just perform check for packages without removal
.TP
\fB\-i\fR, \fB\-\-info\fR
show additional package information
.SH OPTIONS 'ahriman repo-report'
usage: ahriman repo-report [-h] [target ...] usage: ahriman repo-report [-h] [target ...]
generate repository report according to current settings generate repository report according to current settings
@ -632,18 +417,7 @@ generate repository report according to current settings
\fBtarget\fR \fBtarget\fR
target to generate report target to generate report
.SH COMMAND \fI\,'ahriman repo-restore'\/\fR
.SH OPTIONS 'ahriman report'
usage: ahriman repo-report [-h] [target ...]
generate repository report according to current settings
.TP
\fBtarget\fR
target to generate report
.SH OPTIONS 'ahriman repo-restore'
usage: ahriman repo-restore [-h] [-o OUTPUT] path usage: ahriman repo-restore [-h] [-o OUTPUT] path
restore settings and database restore settings and database
@ -652,19 +426,21 @@ restore settings and database
\fBpath\fR \fBpath\fR
path of the input archive path of the input archive
.SH OPTIONS \fI\,'ahriman repo-restore'\/\fR
.TP .TP
\fB\-o\fR \fI\,OUTPUT\/\fR, \fB\-\-output\fR \fI\,OUTPUT\/\fR \fB\-o\fR \fI\,OUTPUT\/\fR, \fB\-\-output\fR \fI\,OUTPUT\/\fR
root path of the extracted files root path of the extracted files
.SH OPTIONS 'ahriman repo-setup' .SH COMMAND \fI\,'ahriman repo-setup'\/\fR
usage: ahriman repo-setup [-h] [--build-as-user BUILD_AS_USER] [--build-command BUILD_COMMAND] usage: ahriman repo-setup [-h] [--build-as-user BUILD_AS_USER] [--build-command BUILD_COMMAND]
[--from-configuration FROM_CONFIGURATION] [--no-multilib] --packager PACKAGER --repository [--from-configuration FROM_CONFIGURATION] [--no-multilib] --packager PACKAGER --repository
REPOSITORY [--sign-key SIGN_KEY] REPOSITORY [--sign-key SIGN_KEY]
[--sign-target {SignSettings.Packages,SignSettings.Repository}] [--web-port WEB_PORT] [--sign-target {SignSettings.Disabled,SignSettings.Packages,SignSettings.Repository}]
[--web-port WEB_PORT]
create initial service configuration, requires root create initial service configuration, requires root
.SH OPTIONS \fI\,'ahriman repo-setup'\/\fR
.TP .TP
\fB\-\-build\-as\-user\fR \fI\,BUILD_AS_USER\/\fR \fB\-\-build\-as\-user\fR \fI\,BUILD_AS_USER\/\fR
force makepkg user to the specific one force makepkg user to the specific one
@ -694,149 +470,14 @@ repository name
sign key id sign key id
.TP .TP
\fB\-\-sign\-target\fR {SignSettings.Packages,SignSettings.Repository} \fB\-\-sign\-target\fR \fI\,{SignSettings.Disabled,SignSettings.Packages,SignSettings.Repository}\/\fR
sign options sign options
.TP .TP
\fB\-\-web\-port\fR \fI\,WEB_PORT\/\fR \fB\-\-web\-port\fR \fI\,WEB_PORT\/\fR
port of the web service port of the web service
.SH OPTIONS 'ahriman init' .SH COMMAND \fI\,'ahriman repo-sign'\/\fR
usage: ahriman repo-setup [-h] [--build-as-user BUILD_AS_USER] [--build-command BUILD_COMMAND]
[--from-configuration FROM_CONFIGURATION] [--no-multilib] --packager PACKAGER --repository
REPOSITORY [--sign-key SIGN_KEY]
[--sign-target {SignSettings.Packages,SignSettings.Repository}] [--web-port WEB_PORT]
create initial service configuration, requires root
.TP
\fB\-\-build\-as\-user\fR \fI\,BUILD_AS_USER\/\fR
force makepkg user to the specific one
.TP
\fB\-\-build\-command\fR \fI\,BUILD_COMMAND\/\fR
build command prefix
.TP
\fB\-\-from\-configuration\fR \fI\,FROM_CONFIGURATION\/\fR
path to default devtools pacman configuration
.TP
\fB\-\-no\-multilib\fR
do not add multilib repository
.TP
\fB\-\-packager\fR \fI\,PACKAGER\/\fR
packager name and email
.TP
\fB\-\-repository\fR \fI\,REPOSITORY\/\fR
repository name
.TP
\fB\-\-sign\-key\fR \fI\,SIGN_KEY\/\fR
sign key id
.TP
\fB\-\-sign\-target\fR {SignSettings.Packages,SignSettings.Repository}
sign options
.TP
\fB\-\-web\-port\fR \fI\,WEB_PORT\/\fR
port of the web service
.SH OPTIONS 'ahriman repo-init'
usage: ahriman repo-setup [-h] [--build-as-user BUILD_AS_USER] [--build-command BUILD_COMMAND]
[--from-configuration FROM_CONFIGURATION] [--no-multilib] --packager PACKAGER --repository
REPOSITORY [--sign-key SIGN_KEY]
[--sign-target {SignSettings.Packages,SignSettings.Repository}] [--web-port WEB_PORT]
create initial service configuration, requires root
.TP
\fB\-\-build\-as\-user\fR \fI\,BUILD_AS_USER\/\fR
force makepkg user to the specific one
.TP
\fB\-\-build\-command\fR \fI\,BUILD_COMMAND\/\fR
build command prefix
.TP
\fB\-\-from\-configuration\fR \fI\,FROM_CONFIGURATION\/\fR
path to default devtools pacman configuration
.TP
\fB\-\-no\-multilib\fR
do not add multilib repository
.TP
\fB\-\-packager\fR \fI\,PACKAGER\/\fR
packager name and email
.TP
\fB\-\-repository\fR \fI\,REPOSITORY\/\fR
repository name
.TP
\fB\-\-sign\-key\fR \fI\,SIGN_KEY\/\fR
sign key id
.TP
\fB\-\-sign\-target\fR {SignSettings.Packages,SignSettings.Repository}
sign options
.TP
\fB\-\-web\-port\fR \fI\,WEB_PORT\/\fR
port of the web service
.SH OPTIONS 'ahriman setup'
usage: ahriman repo-setup [-h] [--build-as-user BUILD_AS_USER] [--build-command BUILD_COMMAND]
[--from-configuration FROM_CONFIGURATION] [--no-multilib] --packager PACKAGER --repository
REPOSITORY [--sign-key SIGN_KEY]
[--sign-target {SignSettings.Packages,SignSettings.Repository}] [--web-port WEB_PORT]
create initial service configuration, requires root
.TP
\fB\-\-build\-as\-user\fR \fI\,BUILD_AS_USER\/\fR
force makepkg user to the specific one
.TP
\fB\-\-build\-command\fR \fI\,BUILD_COMMAND\/\fR
build command prefix
.TP
\fB\-\-from\-configuration\fR \fI\,FROM_CONFIGURATION\/\fR
path to default devtools pacman configuration
.TP
\fB\-\-no\-multilib\fR
do not add multilib repository
.TP
\fB\-\-packager\fR \fI\,PACKAGER\/\fR
packager name and email
.TP
\fB\-\-repository\fR \fI\,REPOSITORY\/\fR
repository name
.TP
\fB\-\-sign\-key\fR \fI\,SIGN_KEY\/\fR
sign key id
.TP
\fB\-\-sign\-target\fR {SignSettings.Packages,SignSettings.Repository}
sign options
.TP
\fB\-\-web\-port\fR \fI\,WEB_PORT\/\fR
port of the web service
.SH OPTIONS 'ahriman repo-sign'
usage: ahriman repo-sign [-h] [package ...] usage: ahriman repo-sign [-h] [package ...]
(re\-)sign packages and repository database according to current settings (re\-)sign packages and repository database according to current settings
@ -845,29 +486,18 @@ usage: ahriman repo-sign [-h] [package ...]
\fBpackage\fR \fBpackage\fR
sign only specified packages sign only specified packages
.SH COMMAND \fI\,'ahriman repo-status-update'\/\fR
.SH OPTIONS 'ahriman sign'
usage: ahriman repo-sign [-h] [package ...]
(re\-)sign packages and repository database according to current settings
.TP
\fBpackage\fR
sign only specified packages
.SH OPTIONS 'ahriman repo-status-update'
usage: ahriman repo-status-update [-h] usage: ahriman repo-status-update [-h]
[-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}] [-s {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}]
update repository status on the status page update repository status on the status page
.SH OPTIONS \fI\,'ahriman repo-status-update'\/\fR
.TP .TP
\fB\-s\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}, \fB\-\-status\fR {BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success} \fB\-s\fR \fI\,{BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}\/\fR, \fB\-\-status\fR \fI\,{BuildStatusEnum.Unknown,BuildStatusEnum.Pending,BuildStatusEnum.Building,BuildStatusEnum.Failed,BuildStatusEnum.Success}\/\fR
new status new status
.SH OPTIONS 'ahriman repo-sync' .SH COMMAND \fI\,'ahriman repo-sync'\/\fR
usage: ahriman repo-sync [-h] [target ...] usage: ahriman repo-sync [-h] [target ...]
sync repository files to remote server according to current settings sync repository files to remote server according to current settings
@ -876,18 +506,7 @@ sync repository files to remote server according to current settings
\fBtarget\fR \fBtarget\fR
target to sync target to sync
.SH COMMAND \fI\,'ahriman repo-update'\/\fR
.SH OPTIONS 'ahriman sync'
usage: ahriman repo-sync [-h] [target ...]
sync repository files to remote server according to current settings
.TP
\fBtarget\fR
target to sync
.SH OPTIONS 'ahriman repo-update'
usage: ahriman repo-update [-h] [--dry-run] [-e] [--no-aur] [--no-local] [--no-manual] [--no-vcs] [package ...] usage: ahriman repo-update [-h] [--dry-run] [-e] [--no-aur] [--no-local] [--no-manual] [--no-vcs] [package ...]
check for packages updates and run build process if requested check for packages updates and run build process if requested
@ -896,6 +515,7 @@ check for packages updates and run build process if requested
\fBpackage\fR \fBpackage\fR
filter check by package base filter check by package base
.SH OPTIONS \fI\,'ahriman repo-update'\/\fR
.TP .TP
\fB\-\-dry\-run\fR \fB\-\-dry\-run\fR
just perform check for updates, same as check command just perform check for updates, same as check command
@ -920,40 +540,7 @@ do not include manual updates
\fB\-\-no\-vcs\fR \fB\-\-no\-vcs\fR
do not check VCS packages do not check VCS packages
.SH OPTIONS 'ahriman update' .SH COMMAND \fI\,'ahriman user-add'\/\fR
usage: ahriman repo-update [-h] [--dry-run] [-e] [--no-aur] [--no-local] [--no-manual] [--no-vcs] [package ...]
check for packages updates and run build process if requested
.TP
\fBpackage\fR
filter check by package base
.TP
\fB\-\-dry\-run\fR
just perform check for updates, same as check command
.TP
\fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty
.TP
\fB\-\-no\-aur\fR
do not check for AUR updates. Implies \-\-no\-vcs
.TP
\fB\-\-no\-local\fR
do not check local packages for updates
.TP
\fB\-\-no\-manual\fR
do not include manual updates
.TP
\fB\-\-no\-vcs\fR
do not check VCS packages
.SH OPTIONS 'ahriman user-add'
usage: ahriman user-add [-h] [--as-service] [-p PASSWORD] [-r {UserAccess.Safe,UserAccess.Read,UserAccess.Write}] [-s] usage: ahriman user-add [-h] [--as-service] [-p PASSWORD] [-r {UserAccess.Safe,UserAccess.Read,UserAccess.Write}] [-s]
username username
@ -963,6 +550,7 @@ update user for web services with the given password and role. In case if passwo
\fBusername\fR \fBusername\fR
username for web service username for web service
.SH OPTIONS \fI\,'ahriman user-add'\/\fR
.TP .TP
\fB\-\-as\-service\fR \fB\-\-as\-service\fR
add user as service user add user as service user
@ -973,14 +561,14 @@ user password. Blank password will be treated as empty password, which is in par
authorization type. authorization type.
.TP .TP
\fB\-r\fR {UserAccess.Safe,UserAccess.Read,UserAccess.Write}, \fB\-\-role\fR {UserAccess.Safe,UserAccess.Read,UserAccess.Write} \fB\-r\fR \fI\,{UserAccess.Safe,UserAccess.Read,UserAccess.Write}\/\fR, \fB\-\-role\fR \fI\,{UserAccess.Safe,UserAccess.Read,UserAccess.Write}\/\fR
user access level user access level
.TP .TP
\fB\-s\fR, \fB\-\-secure\fR \fB\-s\fR, \fB\-\-secure\fR
set file permissions to user\-only set file permissions to user\-only
.SH OPTIONS 'ahriman user-list' .SH COMMAND \fI\,'ahriman user-list'\/\fR
usage: ahriman user-list [-h] [-e] [-r {UserAccess.Safe,UserAccess.Read,UserAccess.Write}] [username] usage: ahriman user-list [-h] [-e] [-r {UserAccess.Safe,UserAccess.Read,UserAccess.Write}] [username]
list users from the user mapping and their roles list users from the user mapping and their roles
@ -989,15 +577,16 @@ list users from the user mapping and their roles
\fBusername\fR \fBusername\fR
filter users by username filter users by username
.SH OPTIONS \fI\,'ahriman user-list'\/\fR
.TP .TP
\fB\-e\fR, \fB\-\-exit\-code\fR \fB\-e\fR, \fB\-\-exit\-code\fR
return non\-zero exit status if result is empty return non\-zero exit status if result is empty
.TP .TP
\fB\-r\fR {UserAccess.Safe,UserAccess.Read,UserAccess.Write}, \fB\-\-role\fR {UserAccess.Safe,UserAccess.Read,UserAccess.Write} \fB\-r\fR \fI\,{UserAccess.Safe,UserAccess.Read,UserAccess.Write}\/\fR, \fB\-\-role\fR \fI\,{UserAccess.Safe,UserAccess.Read,UserAccess.Write}\/\fR
filter users by role filter users by role
.SH OPTIONS 'ahriman user-remove' .SH COMMAND \fI\,'ahriman user-remove'\/\fR
usage: ahriman user-remove [-h] [-s] username usage: ahriman user-remove [-h] [-s] username
remove user from the user mapping and update the configuration remove user from the user mapping and update the configuration
@ -1006,23 +595,26 @@ remove user from the user mapping and update the configuration
\fBusername\fR \fBusername\fR
username for web service username for web service
.SH OPTIONS \fI\,'ahriman user-remove'\/\fR
.TP .TP
\fB\-s\fR, \fB\-\-secure\fR \fB\-s\fR, \fB\-\-secure\fR
set file permissions to user\-only set file permissions to user\-only
.SH OPTIONS 'ahriman web' .SH COMMAND \fI\,'ahriman web'\/\fR
usage: ahriman web [-h] usage: ahriman web [-h]
start web server start web server
.SH COMMENTS .SH COMMENTS
Argument list can also be read from file by using @ prefix. Argument list can also be read from file by using @ prefix.
.SH AUTHORS .SH AUTHORS
.B ahriman .nf
was written by ahriman team <>. ahriman team
.fi.nf
.fi
.SH DISTRIBUTION .SH DISTRIBUTION
The latest version of ahriman may be downloaded from The latest version of ahriman may be downloaded from
.UR https://github.com/arcan1s/ahriman .UR https://github.com/arcan1s/ahriman

10
docs/command-line.rst Normal file
View File

@ -0,0 +1,10 @@
Commands help
=============
ahriman
-------
.. argparse::
:module: ahriman.application.ahriman
:func: _parser
:prog: ahriman

16
docs/conf.py
View File

@ -11,17 +11,16 @@
# documentation root, use os.path.abspath to make it absolute, like shown here. # documentation root, use os.path.abspath to make it absolute, like shown here.
# #
import os import os
import sys
from pathlib import Path from pathlib import Path
# import sys
# sys.path.insert(0, os.path.abspath("."))
basedir = Path(__file__).resolve().parent.parent.parent
metadata_path = basedir / "src/ahriman/version.py"
metadata = {}
with metadata_path.open() as metadata_file:
exec(metadata_file.read(), metadata) # pylint: disable=exec-used
basedir = Path(__file__).resolve().parent.parent / "src"
sys.path.insert(0, str(basedir))
from ahriman.version import __version__
on_rtd = os.environ.get('READTHEDOCS', None) == 'True' on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
@ -32,7 +31,7 @@ copyright = "2021-2022, ahriman team"
author = "ahriman team" author = "ahriman team"
# The full version, including alpha/beta/rc tags # The full version, including alpha/beta/rc tags
release = metadata["__version__"] release = __version__
# -- General configuration --------------------------------------------------- # -- General configuration ---------------------------------------------------
@ -43,6 +42,7 @@ release = metadata["__version__"]
extensions = [ extensions = [
"sphinx.ext.autodoc", "sphinx.ext.autodoc",
"sphinx.ext.napoleon", "sphinx.ext.napoleon",
"sphinxarg.ext",
] ]
# Add any paths that contain templates here, relative to this directory. # Add any paths that contain templates here, relative to this directory.

36
docs/configuration.rst
View File

@ -1,5 +1,5 @@
ahriman configuration Configuration
===================== =============
Some groups can be specified for each architecture separately. E.g. if there are ``build`` and ``build:x86_64`` groups it will use the option from ``build:x86_64`` for the ``x86_64`` architecture and ``build`` for any other (architecture specific group has higher priority). In case if both groups are presented, architecture specific options will be merged into global ones overriding them. Some groups can be specified for each architecture separately. E.g. if there are ``build`` and ``build:x86_64`` groups it will use the option from ``build:x86_64`` for the ``x86_64`` architecture and ``build`` for any other (architecture specific group has higher priority). In case if both groups are presented, architecture specific options will be merged into global ones overriding them.
@ -13,7 +13,7 @@ There are two variable types which have been added to default ones, they are pat
Path values, except for casting to ``pathlib.Path`` type, will be also expanded to absolute paths relative to the configuration path. E.g. if path is set to ``ahriman.ini.d/logging.ini`` and root configuration path is ``/etc/ahriman.ini``\ , the value will be expanded to ``/etc/ahriman.ini.d/logging.ini``. In order to disable path expand, use the full path, e.g. ``/etc/ahriman.ini.d/logging.ini``. Path values, except for casting to ``pathlib.Path`` type, will be also expanded to absolute paths relative to the configuration path. E.g. if path is set to ``ahriman.ini.d/logging.ini`` and root configuration path is ``/etc/ahriman.ini``\ , the value will be expanded to ``/etc/ahriman.ini.d/logging.ini``. In order to disable path expand, use the full path, e.g. ``/etc/ahriman.ini.d/logging.ini``.
``settings`` group ``settings`` group
^^^^^^^^^^^^^^^^^^ ------------------
Base configuration settings. Base configuration settings.
@ -22,7 +22,7 @@ Base configuration settings.
* ``logging`` - path to logging configuration, string, required. Check ``logging.ini`` for reference. * ``logging`` - path to logging configuration, string, required. Check ``logging.ini`` for reference.
``alpm`` group ``alpm`` group
^^^^^^^^^^^^^^ --------------
libalpm and AUR related configuration. libalpm and AUR related configuration.
@ -31,7 +31,7 @@ libalpm and AUR related configuration.
* ``root`` - root for alpm library, string, required. * ``root`` - root for alpm library, string, required.
``auth`` group ``auth`` group
^^^^^^^^^^^^^^ --------------
Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` library to be installed. Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` library to be installed.
@ -47,7 +47,7 @@ Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` libr
Authorized users are stored inside internal database, if any of external provides are used the password field for non-service users must be empty. Authorized users are stored inside internal database, if any of external provides are used the password field for non-service users must be empty.
``build:*`` groups ``build:*`` groups
^^^^^^^^^^^^^^^^^^ ------------------
Build related configuration. Group name can refer to architecture, e.g. ``build:x86_64`` can be used for x86_64 architecture specific settings. Build related configuration. Group name can refer to architecture, e.g. ``build:x86_64`` can be used for x86_64 architecture specific settings.
@ -58,7 +58,7 @@ Build related configuration. Group name can refer to architecture, e.g. ``build:
* ``makechrootpkg_flags`` - additional flags passed to ``makechrootpkg`` command, space separated list of strings, optional. * ``makechrootpkg_flags`` - additional flags passed to ``makechrootpkg`` command, space separated list of strings, optional.
``repository`` group ``repository`` group
^^^^^^^^^^^^^^^^^^^^ --------------------
Base repository settings. Base repository settings.
@ -66,7 +66,7 @@ Base repository settings.
* ``root`` - root path for application, string, required. * ``root`` - root path for application, string, required.
``sign:*`` groups ``sign:*`` groups
^^^^^^^^^^^^^^^^^ -----------------
Settings for signing packages or repository. Group name can refer to architecture, e.g. ``sign:x86_64`` can be used for x86_64 architecture specific settings. Settings for signing packages or repository. Group name can refer to architecture, e.g. ``sign:x86_64`` can be used for x86_64 architecture specific settings.
@ -75,7 +75,7 @@ Settings for signing packages or repository. Group name can refer to architectur
* ``key_*`` settings - PGP key which will be used for specific packages, string, optional. For example, if there is ``key_yay`` option the specified key will be used for yay package and default key for others. * ``key_*`` settings - PGP key which will be used for specific packages, string, optional. For example, if there is ``key_yay`` option the specified key will be used for yay package and default key for others.
``report`` group ``report`` group
^^^^^^^^^^^^^^^^ ----------------
Report generation settings. Report generation settings.
@ -88,14 +88,14 @@ Type will be read from several ways:
* And finally, it will use section name as type. * And finally, it will use section name as type.
``console`` type ``console`` type
"""""""""""""""" ^^^^^^^^^^^^^^^^
Section name must be either ``console`` (plus optional architecture name, e.g. ``console:x86_64``\ ) or random name with ``type`` set. Section name must be either ``console`` (plus optional architecture name, e.g. ``console:x86_64``\ ) or random name with ``type`` set.
* ``use_utf`` - use utf8 symbols in output if set and ascii otherwise, boolean, optional, default ``yes``. * ``use_utf`` - use utf8 symbols in output if set and ascii otherwise, boolean, optional, default ``yes``.
``email`` type ``email`` type
"""""""""""""" ^^^^^^^^^^^^^^
Section name must be either ``email`` (plus optional architecture name, e.g. ``email:x86_64``\ ) or random name with ``type`` set. Section name must be either ``email`` (plus optional architecture name, e.g. ``email:x86_64``\ ) or random name with ``type`` set.
@ -114,7 +114,7 @@ Section name must be either ``email`` (plus optional architecture name, e.g. ``e
* ``user`` - SMTP user to authenticate, string, optional. * ``user`` - SMTP user to authenticate, string, optional.
``html`` type ``html`` type
""""""""""""" ^^^^^^^^^^^^^
Section name must be either ``html`` (plus optional architecture name, e.g. ``html:x86_64``\ ) or random name with ``type`` set. Section name must be either ``html`` (plus optional architecture name, e.g. ``html:x86_64``\ ) or random name with ``type`` set.
@ -125,7 +125,7 @@ Section name must be either ``html`` (plus optional architecture name, e.g. ``ht
* ``template_path`` - path to Jinja2 template, string, required. * ``template_path`` - path to Jinja2 template, string, required.
``telegram`` type ``telegram`` type
""""""""""""""""" ^^^^^^^^^^^^^^^^^
Section name must be either ``telegram`` (plus optional architecture name, e.g. ``telegram:x86_64``\ ) or random name with ``type`` set. Section name must be either ``telegram`` (plus optional architecture name, e.g. ``telegram:x86_64``\ ) or random name with ``type`` set.
@ -138,7 +138,7 @@ Section name must be either ``telegram`` (plus optional architecture name, e.g.
* ``template_type`` - ``parse_mode`` to be passed to telegram API, one of ``MarkdownV2``\ , ``HTML``\ , ``Markdown``\ , string, optional, default ``HTML``. * ``template_type`` - ``parse_mode`` to be passed to telegram API, one of ``MarkdownV2``\ , ``HTML``\ , ``Markdown``\ , string, optional, default ``HTML``.
``upload`` group ``upload`` group
^^^^^^^^^^^^^^^^ ----------------
Remote synchronization settings. Remote synchronization settings.
@ -151,7 +151,7 @@ Type will be read from several ways:
* And finally, it will use section name as type. * And finally, it will use section name as type.
``github`` type ``github`` type
""""""""""""""" ^^^^^^^^^^^^^^^
This feature requires Github key creation (see below). Section name must be either ``github`` (plus optional architecture name, e.g. ``github:x86_64``\ ) or random name with ``type`` set. This feature requires Github key creation (see below). Section name must be either ``github`` (plus optional architecture name, e.g. ``github:x86_64``\ ) or random name with ``type`` set.
@ -168,7 +168,7 @@ This feature requires Github key creation (see below). Section name must be eith
* ``username`` - Github authorization user, string, required. Basically the same as ``owner``. * ``username`` - Github authorization user, string, required. Basically the same as ``owner``.
``rsync`` type ``rsync`` type
"""""""""""""" ^^^^^^^^^^^^^^
Requires ``rsync`` package to be installed. Do not forget to configure ssh for user ``ahriman``. Section name must be either ``rsync`` (plus optional architecture name, e.g. ``rsync:x86_64``\ ) or random name with ``type`` set. Requires ``rsync`` package to be installed. Do not forget to configure ssh for user ``ahriman``. Section name must be either ``rsync`` (plus optional architecture name, e.g. ``rsync:x86_64``\ ) or random name with ``type`` set.
@ -177,7 +177,7 @@ Requires ``rsync`` package to be installed. Do not forget to configure ssh for u
* ``remote`` - remote server to rsync (e.g. ``1.2.3.4:path/to/sync``\ ), string, required. * ``remote`` - remote server to rsync (e.g. ``1.2.3.4:path/to/sync``\ ), string, required.
``s3`` type ``s3`` type
""""""""""" ^^^^^^^^^^^
Requires ``boto3`` library to be installed. Section name must be either ``s3`` (plus optional architecture name, e.g. ``s3:x86_64``\ ) or random name with ``type`` set. Requires ``boto3`` library to be installed. Section name must be either ``s3`` (plus optional architecture name, e.g. ``s3:x86_64``\ ) or random name with ``type`` set.
@ -189,7 +189,7 @@ Requires ``boto3`` library to be installed. Section name must be either ``s3`` (
* ``secret_key`` - AWS secret access key, string, required. * ``secret_key`` - AWS secret access key, string, required.
``web:*`` groups ``web:*`` groups
^^^^^^^^^^^^^^^^ ----------------
Web server settings. If any of ``host``\ /\ ``port`` is not set, web integration will be disabled. Group name can refer to architecture, e.g. ``web:x86_64`` can be used for x86_64 architecture specific settings. This feature requires ``aiohttp`` libraries to be installed. Web server settings. If any of ``host``\ /\ ``port`` is not set, web integration will be disabled. Group name can refer to architecture, e.g. ``web:x86_64`` can be used for x86_64 architecture specific settings. This feature requires ``aiohttp`` libraries to be installed.

621
docs/faq.md
View File

@ -1,621 +0,0 @@
# FAQ
## General topics
### What is the purpose of the project?
This project has been created in order to maintain self-hosted Arch Linux user repository without manual intervention - checking for updates and building packages.
### How do I install it?
TL;DR
```shell
yay -S ahriman
sudo ahriman -a x86_64 repo-setup --packager "ahriman bot <ahriman@example.com>" --repository "repository"
systemctl enable --now ahriman@x86_64.timer
```
#### Long answer
The idea is to install the package as usual, create working directory tree, create configuration for `sudo` and `devtools`. Detailed description of the setup instruction can be found [here](setup.md).
### What does "architecture specific" mean? / How to configure for different architectures?
Some sections can be configured per architecture. The service will merge architecture specific values into common settings. In order to specify settings for specific architecture you must point it in section name.
For example, the section
```ini
[build]
build_command = extra-x86_64-build
```
states that default build command is `extra-x86_64-build`. But if there is section
```ini
[build:i686]
build_command = extra-i686-build
```
the `extra-i686-build` command will be used for `i686` architecture.
### How to use reporter/upload settings?
Normally you probably like to generate only one report for the specific type, e.g. only one email report. In order to do it you will need to have the following configuration:
```ini
[report]
target = email
[email]
...
```
or in case of multiple architectures and _different_ reporting settings:
```ini
[report]
target = email
[email:i686]
...
[email:x86_64]
...
```
But for some cases you would like to have multiple different reports with the same type (e.g. sending different templates to different addresses). For these cases you will need to specify section name in target and type in section, e.g. the following configuration can be used:
```ini
[report]
target = email_1 email_2
[email_1]
type = email
...
[email_2]
type = email
...
```
### Okay, I've installed ahriman, how do I add new package?
```shell
sudo -u ahriman ahriman package-add ahriman --now
```
`--now` flag is totally optional and just run `repo-update` subcommand after the registering the new package, Thus the extended flow is the following:
```shell
sudo -u ahriman ahriman package-add ahriman
sudo -u ahriman ahriman repo-update
```
### AUR is fine, but I would like to create package from local PKGBUILD
TL;DR
```shell
sudo -u ahriman ahriman package-add /path/to/local/directory/with/PKGBUILD --now
```
Before using this command you will need to create local directory, put `PKGBUILD` there and generate `.SRCINFO` by using `makepkg --printsrcinfo > .SRCINFO` command. These packages will be stored locally and _will be ignored_ during automatic update; in order to update the package you will need to run `package-add` command again.
### But I just wanted to change PKGBUILD from AUR a bit!
Well it is supported also.
1. Clone sources from AUR.
2. Make changes you would like to (e.g. edit `PKGBUILD`, add external patches).
3. Run `sudo -u ahriman ahriman patch-add /path/to/local/directory/with/PKGBUILD`.
The last command will calculate diff from current tree to the `HEAD` and will store it locally. Patches will be applied on any package actions (e.g. it can be used for dependency management).
### Hey, I would like to rebuild the official repository package
So it is the same as adding any other package, but due to restrictions you must specify source explicitly, e.g.:
```shell
sudo -u ahriman ahriman package-add pacmann -s repository
```
### Package build fails because it cannot validate PGP signature of source files
TL;DR
```shell
sudo -u ahriman ahriman key-import ...
```
### How do I check if there are new commits for VCS packages?
Normally the service handles VCS packages correctly, but it requires additional dependencies:
```shell
pacman -S breezy darcs mercurial subversion
```
### I would like to remove package because it is no longer needed/moved to official repositories
```shell
sudo -u ahriman ahriman package-remove ahriman
```
Also, there is command `repo-remove-unknown` which checks packages in AUR and local storage and removes ones which have been removed.
Remove commands also remove any package files (patches, caches etc).
### There is new major release of %library-name%, how do I rebuild packages?
TL;DR
```shell
sudo -u ahriman ahriman repo-rebuild --depends-on python
```
You can even rebuild the whole repository (which is particular useful in case if you would like to change packager) if you do not supply `--depends-on` option.
However, note that you do not need to rebuild repository in case if you just changed signing option, just use `repo-sign` command instead.
### Hmm, I have packages built, but how can I use it?
Add the following lines to your `pacman.conf`:
```ini
[repository]
Server = file:///var/lib/ahriman/repository/x86_64
```
(You might need to add `SigLevel` option according to the pacman documentation.)
### I would like to serve the repository
Easy. For example, nginx configuration (without SSL) will look like:
```
server {
listen 80;
server_name repo.example.com;
location / {
autoindex on;
root /var/lib/ahriman/repository;
}
}
```
Example of the status page configuration is the following (status service is using 8080 port):
```
server {
listen 80;
server_name builds.example.com;
location / {
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarder-Proto $scheme;
proxy_pass http://127.0.0.1:8080;
}
}
```
## Docker image
We provide official images which can be found under `arcan1s/ahriman` repository. Docker image is being updated on each master commit as well as on each version. If you would like to use last (probably unstable) build you can use `edge` tag or `latest` for any tagged versions; otherwise you can use any version tag available.
The default action (in case if no arguments provided) is `repo-update`. Basically the idea is to run container, e.g.:
```shell
docker run --privileged -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
```
`--privileged` flag is required to make mount possible inside container. In addition, you can pass own configuration overrides by using the same `-v` flag, e.g.:
```shell
docker run -v /path/to/local/repo:/var/lib/ahriman -v /etc/ahriman.ini:/etc/ahriman.ini.d/10-overrides.ini arcan1s/ahriman:latest
```
By default, it runs `repo-update`, but it can be overwritten to any other command you would like to, e.g.:
```shell
docker run arcan1s/ahriman:latest package-add ahriman --now
```
For more details please refer to docker FAQ.
### Environment variables
The following environment variables are supported:
* `AHRIMAN_ARCHITECTURE` - architecture of the repository, default is `x86_64`.
* `AHRIMAN_DEBUG` - if set all commands will be logged to console.
* `AHRIMAN_FORCE_ROOT` - force run ahriman as root instead of guessing by subcommand.
* `AHRIMAN_HOST` - host for the web interface, default is `0.0.0.0`.
* `AHRIMAN_OUTPUT` - controls logging handler, e.g. `syslog`, `console`. The name must be found in logging configuration. Note that if `syslog` (the default) handler is used you will need to mount `/dev/log` inside container because it is not available there.
* `AHRIMAN_PACKAGER` - packager name from which packages will be built, default is `ahriman bot <ahriman@example.com>`.
* `AHRIMAN_PORT` - HTTP server port if any, default is empty.
* `AHRIMAN_REPOSITORY` - repository name, default is `aur-clone`.
* `AHRIMAN_REPOSITORY_ROOT` - repository root. Because of filesystem rights it is required to override default repository root. By default, it uses `ahriman` directory inside ahriman's home, which can be passed as mount volume.
* `AHRIMAN_USER` - ahriman user, usually must not be overwritten, default is `ahriman`.
You can pass any of these variables by using `-e` argument, e.g.:
```shell
docker run -e AHRIMAN_PORT=8080 arcan1s/ahriman:latest
```
### Web service setup
Well for that you would need to have web container instance running forever; it can be achieved by the following command:
```shell
docker run -p 8080:8080 -e AHRIMAN_PORT=8080 -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
```
Note about `AHRIMAN_PORT` environment variable which is required in order to enable web service. An additional port bind by `-p 8080:8080` is required to pass docker port outside of container.
For every next container run use arguments `-e AHRIMAN_PORT=8080 --net=host`, e.g.:
```shell
docker run --privileged -e AHRIMAN_PORT=8080 --net=host -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
```
## Remote synchronization
### Wait I would like to use the repository from another server
There are several choices:
1. Easy and cheap, just share your local files through the internet, e.g. for `nginx`:
```
server {
location /x86_64 {
root /var/lib/ahriman/repository/x86_64;
autoindex on;
}
}
```
2. You can also upload your packages using `rsync` to any available server. In order to use it you would need to configure ahriman first:
```ini
[upload]
target = rsync
[rsync]
remote = 192.168.0.1:/srv/repo
```
After that just add `/srv/repo` to the `pacman.conf` as usual. You can also upload to S3 (e.g. `Server = https://s3.eu-central-1.amazonaws.com/repository/x86_64`) or to Github (e.g. `Server = https://github.com/ahriman/repository/releases/download/x86_64`).
### How do I configure S3?
1. Install dependencies:
```shell
pacman -S python-boto3
```
3. Create a bucket.
4. Create user with write access to the bucket:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ListObjectsInBucket",
"Effect": "Allow",
"Action": [
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::repository"
]
},
{
"Sid": "AllObjectActions",
"Effect": "Allow",
"Action": "s3:*Object",
"Resource": [
"arn:aws:s3:::repository/*"
]
}
]
}
```
5. Create an API key for the user and store it.
6. Configure the service as following:
```ini
[upload]
target = s3
[s3]
access_key = ...
bucket = repository
region = eu-central-1
secret_key = ...
```
### How do I configure Github?
1. Create a repository.
2. [Create API key](https://github.com/settings/tokens) with scope `public_repo`.
3. Configure the service as following:
```ini
[upload]
target = github
[github]
owner = ahriman
password = ...
repository = repository
username = ahriman
```
## Reporting
### I would like to get report to email
1. Install dependencies:
```shell
yay -S python-jinja
```
2. Configure the service:
```ini
[report]
target = email
[email]
host = smtp.example.com
link_path = http://example.com/x86_64
password = ...
port = 465
receivers = me@example.com
sender = me@example.com
user = me@example.com
```
### I'm using synchronization to S3 and would like to generate index page
1. Install dependencies:
```shell
yay -S python-jinja
```
2. Configure the service:
```ini
[report]
target = html
[html]
path = /var/lib/ahriman/repository/x86_64/index.html
link_path = http://example.com/x86_64
```
After these steps `index.html` file will be automatically synced to S3
### I would like to get messages to my telegram account/channel
1. It still requires additional dependencies:
```shell
yay -S python-jinja
```
2. Register bot in telegram. You can do it by talking with [@BotFather](https://t.me/botfather). For more details please refer to [official documentation](https://core.telegram.org/bots).
3. Optionally (if you want to post message in chat):
1. Create telegram channel.
2. Invite your bot into the channel.
3. Make your channel public
4. Get chat id if you want to use by numerical id or just use id prefixed with `@` (e.g. `@ahriman`). If you are not using chat the chat id is your user id. If you don't want to make channel public you can use [this guide](https://stackoverflow.com/a/33862907).
5. Configure the service:
```ini
[report]
target = telegram
[telegram]
api_key = aaAAbbBBccCC
chat_id = @ahriman
link_path = http://example.com/x86_64
```
`api_key` is the one sent by [@BotFather](https://t.me/botfather), `chat_id` is the value retrieved from previous step.
If you did everything fine you should receive the message with the next update. Quick credentials check can be done by using the following command:
```shell
curl 'https://api.telegram.org/bot${CHAT_ID}/sendMessage?chat_id=${API_KEY}&text=hello'
```
(replace `${CHAT_ID}` and `${API_KEY}` with the values from configuration).
## Web service
### Readme mentions web interface, how do I use it?
1. Install dependencies:
```shell
yay -S python-aiohttp python-aiohttp-jinja2
```
2. Configure service:
```ini
[web]
port = 8080
```
3. Start the web service `systemctl enable --now ahriman-web@x86_64`.
### I would like to limit user access to the status page
1. Install dependencies 😊:
```shell
yay -S python-aiohttp-security python-aiohttp-session python-cryptography
```
2. Configure the service to enable authorization:
```ini
[auth]
target = configuration
```
3. Create user for the service:
```shell
sudo -u ahriman ahriman user-add --as-service -r write api
```
This command will ask for the password, just type it in stdin; _do not_ leave the field blank, user will not be able to authorize.
4. Create end-user `sudo -u ahriman ahriman user-add -r write my-first-user` with password.
5. Restart web service `systemctl restart ahriman-web@x86_64`.
### I would like to use OAuth
1. Create OAuth web application, download its `client_id` and `client_secret`.
2. Guess what? Install dependencies:
```shell
yay -S python-aiohttp-security python-aiohttp-session python-cryptography python-aioauth-client
```
3. Configure the service:
```ini
[auth]
target = oauth
client_id = ...
client_secret = ...
[web]
address = https://example.com
```
Configure `oauth_provider` and `oauth_scopes` in case if you would like to use different from Google provider. Scope must grant access to user email. `web.address` is required to make callback URL available from internet.
4. Create service user:
```shell
sudo -u ahriman ahriman user-add --as-service -r write api
```
5. Create end-user `sudo -u ahriman ahriman user-add -r write my-first-user`. When it will ask for the password leave it blank.
6. Restart web service `systemctl restart ahriman-web@x86_64`.
## Backup and restore
The service provides several commands aim to do easy repository backup and restore. If you would like to move repository from the server `server1.example.com` to another `server2.example.com` you have to perform the following steps:
1. On the source server `server1.example.com` run `repo-backup` command, e.g.:
```shell
sudo ahriman repo-backup /tmp/repo.tar.gz
```
This command will pack all configuration files together with database file into the archive specified as command line argument (i.e. `/tmp/repo.tar.gz`). In addition it will also archive `cache` directory (the one which contains local clones used by e.g. local packages) and `.gnupg` of the `ahriman` user.
2. Copy created archive from source server `server1.example.com` to target `server2.example.com`.
3. Install ahriman as usual on the target server `server2.example.com` if you didn't yet.
4. Extract archive e.g. by using subcommand:
```shell
sudo ahriman repo-restore /tmp/repo.tar.gz
```
An additional argument `-o`/`--output` can be used to specify extraction root (`/` by default).
5. Rebuild repository:
```shell
sudo -u ahriman ahriman repo-rebuild --from-database
```
## Other topics
### How does it differ from %another-manager%?
Short answer - I do not know.
#### [archrepo2](https://github.com/lilydjwg/archrepo2)
Don't know, haven't tried it. But it lacks of documentation at least.
* Web interface.
* No synchronization and reporting.
* `archrepo2` actively uses direct shell calls and `yaourt` components.
* It has constantly running process instead of timer process (it is not pro or con).
#### [repoctl](https://github.com/cassava/repoctl)
* Web interface.
* No reporting.
* Local packages and patches support.
* Some actions are not fully automated (e.g. package update still requires manual intervention for the build itself).
* `repoctl` has better AUR interaction features. With colors!
* `repoctl` has much easier configuration and even completion.
* `repoctl` is able to store old packages.
* Ability to host repository from same command vs external services (e.g. nginx) in `ahriman`.
#### [repo-scripts](https://github.com/arcan1s/repo-scripts)
Though originally I've created ahriman by trying to improve the project, it still lacks a lot of features:
* Web interface.
* Better reporting with template support.
* Synchronization features (there was only `rsync` based).
* Local packages and patches support.
* No dependency management.
* And so on.
`repo-scripts` also have bad architecture and bad quality code and uses out-of-dated `yaourt` and `package-query`.
#### [toolbox](https://github.com/chaotic-aur/toolbox)
It is automation tools for `repoctl` mentioned above. Except for using shell it looks pretty cool and also offers some additional features like patches, remote synchronization (isn't it?) and reporting.
### I would like to check service logs
By default, the service writes logs to `/dev/log` which can be accessed by using `journalctl` command (logs are written to the journal of the user under which command is run).
You can also edit configuration and forward logs to `stderr`, just change `handlers` value, e.g.:
```shell
sed -i 's/handlers = syslog_handler/handlers = console_handler/g' /etc/ahriman.ini.d/logging.ini
```
You can even configure logging as you wish, but kindly refer to python `logging` module [configuration](https://docs.python.org/3/library/logging.config.html).
### Html customization
It is possible to customize html templates. In order to do so, create files somewhere (refer to Jinja2 documentation and the service source code for available parameters) and put `template_path` to configuration pointing to this directory.
### I did not find my question
[Create an issue](https://github.com/arcan1s/ahriman/issues) with type **Question**.

7
docs/index.rst
View File

@ -21,7 +21,12 @@ Contents
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
usage setup
configuration
command-line
faq
architecture
advanced-usage
Indices and tables Indices and tables
------------------ ------------------

66
docs/setup.md
View File

@ -1,66 +0,0 @@
# Setup instructions
1. Install package as usual.
2. Change settings if required, see [configuration reference](configuration.md) for more details.
3. TL;DR
```shell
sudo ahriman -a x86_64 repo-setup ...
```
`repo-setup` literally does the following steps:
1. Create `/var/lib/ahriman/.makepkg.conf` with `makepkg.conf` overrides if required (at least you might want to set `PACKAGER`):
```shell
echo 'PACKAGER="John Doe <john@doe.com>"' | sudo -u ahriman tee -a /var/lib/ahriman/.makepkg.conf
```
2. Configure build tools (it is required for correct dependency management system):
1. Create build command, e.g. `ln -s /usr/bin/archbuild /usr/local/bin/ahriman-x86_64-build` (you can choose any name for command, basically it should be `{name}-{arch}-build`).
2. Create configuration file, e.g. `cp /usr/share/devtools/pacman-{extra,ahriman}.conf` (same as previous `pacman-{name}.conf`).
3. Change configuration file, add your own repository, add multilib repository etc;
4. Set `build_command` option to point to your command.
5. Configure `/etc/sudoers.d/ahriman` to allow running command without a password.
```shell
ln -s /usr/bin/archbuild /usr/local/bin/ahriman-x86_64-build
cp /usr/share/devtools/pacman-{extra,ahriman}.conf
echo '[multilib]' | tee -a /usr/share/devtools/pacman-ahriman.conf
echo 'Include = /etc/pacman.d/mirrorlist' | tee -a /usr/share/devtools/pacman-ahriman.conf
echo '[aur-clone]' | tee -a /usr/share/devtools/pacman-ahriman.conf
echo 'SigLevel = Optional TrustAll' | tee -a /usr/share/devtools/pacman-ahriman.conf
echo 'Server = file:///var/lib/ahriman/repository/$arch' | tee -a /usr/share/devtools/pacman-ahriman.conf
echo '[build]' | tee -a /etc/ahriman.ini.d/build.ini
echo 'build_command = ahriman-x86_64-build' | tee -a /etc/ahriman.ini.d/build.ini
echo 'Cmnd_Alias CARCHBUILD_CMD = /usr/local/bin/ahriman-x86_64-build *' | tee -a /etc/sudoers.d/ahriman
echo 'ahriman ALL=(ALL) NOPASSWD: CARCHBUILD_CMD' | tee -a /etc/sudoers.d/ahriman
chmod 400 /etc/sudoers.d/ahriman
```
4. Start and enable `ahriman@.timer` via `systemctl`:
```shell
systemctl enable --now ahriman@x86_64.timer
```
5. Start and enable status page:
```shell
systemctl enable --now ahriman-web@x86_64
```
6. Add packages by using `ahriman package-add {package}` command:
```shell
sudo -u ahriman ahriman -a x86_64 package-add ahriman --now
```
## User creation
`user-add` subcommand is recommended for new user creation.

9
docs/setup.rst
View File

@ -1,5 +1,5 @@
Setup instructions Initial setup
================== =============
#. #.
Install package as usual. Install package as usual.
@ -74,8 +74,3 @@ Setup instructions
.. code-block:: shell .. code-block:: shell
sudo -u ahriman ahriman -a x86_64 package-add ahriman --now sudo -u ahriman ahriman -a x86_64 package-add ahriman --now
User creation
-------------
``user-add`` subcommand is recommended for new user creation.

33
docs/usage.rst
View File

@ -1,33 +0,0 @@
Basic usage
===========
Depending on the goal the package can be used in different ways. Nevertheless, in the most cases you will need some basic classes::
from pathlib import Path
from ahriman.core.configuration import Configuration
from ahriman.core.database.sqlite import SQLite
architecture = "x86_64"
configuration = Configuration.from_path(Path("/etc/ahriman.ini"), architecture, quiet=False)
sqlite = SQLite.load(configuration)
At this point there are ``configuration`` and ``database`` instances which can be used later at any time anywhere, e.g.::
# instance of ``RepositoryPaths`` class
paths = configuration.repository_paths
Almost all actions are wrapped by ``ahriman.core.repository.Repository`` class::
from ahriman.core.repository import Repository
repository = Repository(architecture, configuration, database, no_report=False, unsafe=False)
And the ``repository`` instance can be used to perform repository maintenance::
build_result = repository.process_build(known_packages)
built_packages = repository.packages_built()
update_result = repository.process_update(built_packages)
repository.process_report(None, update_result)
repository.process_sync(None, update_result.success)

1
setup.py
View File

@ -96,6 +96,7 @@ setup(
"Sphinx", "Sphinx",
"argparse-manpage", "argparse-manpage",
"pydeps", "pydeps",
"sphinx-argparse",
"sphinxcontrib-napoleon", "sphinxcontrib-napoleon",
], ],
# FIXME technically this dependency is required, but in some cases we do not have access to # FIXME technically this dependency is required, but in some cases we do not have access to

4
tox.ini
View File

@ -37,14 +37,14 @@ setenv =
commands = commands =
argparse-manpage --module ahriman.application.ahriman --function _parser --author "ahriman team" --project-name ahriman --author-email "" --url https://github.com/arcan1s/ahriman --output ../docs/ahriman.1 argparse-manpage --module ahriman.application.ahriman --function _parser --author "ahriman team" --project-name ahriman --author-email "" --url https://github.com/arcan1s/ahriman --output ../docs/ahriman.1
pydeps ahriman -o ../docs/ahriman-architecture.svg --no-config --no-show --cluster pydeps ahriman -o ../docs/ahriman-architecture.svg --no-config --no-show --cluster
sphinx-apidoc --force -o ../docs/source . sphinx-apidoc --force -o ../docs .
[testenv:docs-html] [testenv:docs-html]
deps = deps =
{[tox]dependencies} {[tox]dependencies}
-e .[docs] -e .[docs]
commands = commands =
sphinx-build -b html -a -j auto docs/source docs/html sphinx-build -b html -a -j auto docs docs/html
[testenv:tests] [testenv:tests]
deps = deps =