mirror of
https://github.com/arcan1s/ahriman.git
synced 2025-06-28 06:41:43 +00:00
docs: improve application help messages
This commit is contained in:
@ -11,7 +11,7 @@ Depending on the goal the package can be used in different ways. Nevertheless, i
|
||||
from ahriman.core.database import SQLite
|
||||
from ahriman.models.repository_id import RepositoryId
|
||||
|
||||
repository_id = RepositoryId("x86_64", "aur-clone")
|
||||
repository_id = RepositoryId("x86_64", "aur")
|
||||
configuration = Configuration.from_path(Path("/etc/ahriman.ini"), repository_id)
|
||||
database = SQLite.load(configuration)
|
||||
|
||||
|
||||
@ -21,6 +21,14 @@ ahriman.application.ahriman module
|
||||
:no-undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
ahriman.application.help\_formatter module
|
||||
------------------------------------------
|
||||
|
||||
.. automodule:: ahriman.application.help_formatter
|
||||
:members:
|
||||
:no-undoc-members:
|
||||
:show-inheritance:
|
||||
|
||||
ahriman.application.lock module
|
||||
-------------------------------
|
||||
|
||||
|
||||
@ -118,12 +118,12 @@ Having default root as ``/var/lib/ahriman`` (differs from container though), the
|
||||
├── ahriman.db
|
||||
├── cache
|
||||
├── chroot
|
||||
│ └── aur-clone
|
||||
│ └── aur
|
||||
├── packages
|
||||
│ └── aur-clone
|
||||
│ └── aur
|
||||
│ └── x86_64
|
||||
├── pacman
|
||||
│ └── aur-clone
|
||||
│ └── aur
|
||||
│ └── x86_64
|
||||
│ ├── local
|
||||
│ │ └── ALPM_DB_VERSION
|
||||
@ -133,12 +133,12 @@ Having default root as ``/var/lib/ahriman`` (differs from container though), the
|
||||
│ └── multilib.db
|
||||
│
|
||||
└── repository
|
||||
└── aur-clone
|
||||
└── aur
|
||||
└── x86_64
|
||||
├── aur-clone.db -> aur-clone.db.tar.gz
|
||||
├── aur-clone.db.tar.gz
|
||||
├── aur-clone.files -> aur-clone.files.tar.gz
|
||||
└── aur-clone.files.tar.gz
|
||||
├── aur.db -> aur.db.tar.gz
|
||||
├── aur.db.tar.gz
|
||||
├── aur.files -> aur.files.tar.gz
|
||||
└── aur.files.tar.gz
|
||||
|
||||
There are multiple subdirectories, some of them are commons for any repository, but some of them are not.
|
||||
|
||||
@ -371,7 +371,7 @@ There are several supported synchronization providers, currently they are ``rsyn
|
||||
|
||||
``rsync`` provider does not have any specific logic except for running external rsync application with configured arguments. The service does not handle SSH configuration, thus it has to be configured before running application manually.
|
||||
|
||||
``s3`` provider uses ``boto3`` package and implements sync feature. The files are stored in architecture specific directory (e.g. if bucket is ``repository``, packages will be stored in ``repository/aur-clone/x86_64`` for the ``aur-clone`` repository and ``x86_64`` architecture), bucket must be created before any action and API key must have permissions to write to the bucket. No external configuration required. In order to upload only changed files the service compares calculated hashes with the Amazon ETags, the implementation used is described `here <https://teppen.io/2018/10/23/aws_s3_verify_etags/>`__.
|
||||
``s3`` provider uses ``boto3`` package and implements sync feature. The files are stored in architecture specific directory (e.g. if bucket is ``repository``, packages will be stored in ``repository/aur/x86_64`` for the ``aur`` repository and ``x86_64`` architecture), bucket must be created before any action and API key must have permissions to write to the bucket. No external configuration required. In order to upload only changed files the service compares calculated hashes with the Amazon ETags, the implementation used is described `here <https://teppen.io/2018/10/23/aws_s3_verify_etags/>`__.
|
||||
|
||||
``github`` provider authenticates through basic auth, API key with repository write permissions is required. There will be created a release with the name of the architecture in case if it does not exist; files will be uploaded to the release assets. It also stores array of files and their MD5 checksums in release body in order to upload only changed ones. According to the GitHub API in case if there is already uploaded asset with the same name (e.g. database files), asset will be removed first.
|
||||
|
||||
|
||||
@ -3,8 +3,8 @@ Configuration
|
||||
|
||||
Some groups can be specified for each architecture and/or repository separately. E.g. if there are ``build`` and ``build:x86_64`` groups it will use an 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. The order which will be used for option resolution is the following:
|
||||
|
||||
#. Repository and architecture specific, e.g. ``build:aur-clone:x86_64``.
|
||||
#. Repository specific, e.g. ``build:aur-clone``.
|
||||
#. Repository and architecture specific, e.g. ``build:aur:x86_64``.
|
||||
#. Repository specific, e.g. ``build:aur``.
|
||||
#. Architecture specific, e.g. ``build:x86_64``.
|
||||
#. Default section, e.g. ``build``.
|
||||
|
||||
|
||||
@ -46,7 +46,7 @@ The following environment variables are supported:
|
||||
* ``AHRIMAN_PORT`` - HTTP server port if any, default is empty.
|
||||
* ``AHRIMAN_POSTSETUP_COMMAND`` - if set, the command which will be called (as root) after the setup command, but before any other actions.
|
||||
* ``AHRIMAN_PRESETUP_COMMAND`` - if set, the command which will be called (as root) right before the setup command.
|
||||
* ``AHRIMAN_REPOSITORY`` - repository name, default is ``aur-clone``.
|
||||
* ``AHRIMAN_REPOSITORY`` - repository name, default is ``aur``.
|
||||
* ``AHRIMAN_REPOSITORY_SERVER`` - optional override for the repository URL. Useful if you would like to download packages from remote instead of local filesystem.
|
||||
* ``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_UNIX_SOCKET`` - full path to unix socket which is used by web server, default is empty. Note that more likely you would like to put it inside ``AHRIMAN_REPOSITORY_ROOT`` directory (e.g. ``/var/lib/ahriman/ahriman/ahriman-web.sock``) or to ``/run/ahriman``.
|
||||
@ -106,9 +106,9 @@ In order to create configuration for additional repositories, the ``AHRIMAN_POST
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -e AHRIMAN_POSTSETUP_COMMAND="ahriman --architecture x86_64 --repository aur-clone-v2 service-setup --build-as-user ahriman --packager 'ahriman bot <ahriman@example.com>'" -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
|
||||
docker run --privileged -p 8080:8080 -e AHRIMAN_PORT=8080 -e AHRIMAN_UNIX_SOCKET=/var/lib/ahriman/ahriman/ahriman-web.sock -e AHRIMAN_POSTSETUP_COMMAND="ahriman --architecture x86_64 --repository aur-v2 service-setup --build-as-user ahriman --packager 'ahriman bot <ahriman@example.com>'" -v /path/to/local/repo:/var/lib/ahriman arcan1s/ahriman:latest
|
||||
|
||||
The command above will also create configuration for the repository named ``aur-clone-v2``.
|
||||
The command above will also create configuration for the repository named ``aur-v2``.
|
||||
|
||||
Note, however, that the command above is only required in case if the service is going to be used to run subprocesses. Otherwise, everything else (web interface, status, etc) will be handled as usual.
|
||||
|
||||
|
||||
@ -14,8 +14,8 @@ TL;DR
|
||||
.. code-block:: shell
|
||||
|
||||
yay -S ahriman
|
||||
ahriman -a x86_64 -r aur-clone service-setup --packager "ahriman bot <ahriman@example.com>"
|
||||
systemctl enable --now ahriman@x86_64-aur-clone.timer
|
||||
ahriman -a x86_64 -r aur service-setup --packager "ahriman bot <ahriman@example.com>"
|
||||
systemctl enable --now ahriman@x86_64-aur.timer
|
||||
|
||||
Long answer
|
||||
"""""""""""
|
||||
@ -29,7 +29,7 @@ The alternative way (though not recommended) is to run service instead of timer:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
systemctl enable --now ahriman-daemon@x86_64-aur-clone
|
||||
systemctl enable --now ahriman-daemon@x86_64-aur
|
||||
|
||||
How to validate settings
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@ -77,7 +77,7 @@ states that default build command is ``extra-x86_64-build``. But if there is sec
|
||||
[build:i686]
|
||||
build_command = extra-i686-build
|
||||
|
||||
the ``extra-i686-build`` command will be used for ``i686`` architecture. You can also override settings for different repositories and architectures; in this case section names will be ``build:aur-clone`` (repository name only) and ``build:aur-clone:i686`` (both repository name and architecture).
|
||||
the ``extra-i686-build`` command will be used for ``i686`` architecture. You can also override settings for different repositories and architectures; in this case section names will be ``build:aur`` (repository name only) and ``build:aur:i686`` (both repository name and architecture).
|
||||
|
||||
How to generate build reports
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -30,9 +30,9 @@ The application provides special plugin which generates keyring package. This pl
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman package-add aur-clone-keyring --source local --now
|
||||
sudo -u ahriman ahriman package-add aur-keyring --source local --now
|
||||
|
||||
where ``aur-clone`` is your repository name.
|
||||
where ``aur`` is your repository name.
|
||||
|
||||
This plugin might have some issues, in case of any of them, kindly create `new issue <https://github.com/arcan1s/ahriman/issues/new/choose>`__.
|
||||
|
||||
@ -68,6 +68,6 @@ The application provides special plugin which generates mirrorlist package also.
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo -u ahriman ahriman package-add aur-clone-mirrorlist --source local --now
|
||||
sudo -u ahriman ahriman package-add aur-mirrorlist --source local --now
|
||||
|
||||
where ``aur-clone`` is your repository name.
|
||||
where ``aur`` is your repository name.
|
||||
|
||||
@ -21,7 +21,7 @@ How to report by email
|
||||
|
||||
[email]
|
||||
host = smtp.example.com
|
||||
link_path = http://example.com/aur-clone/x86_64
|
||||
link_path = http://example.com/aur/x86_64
|
||||
password = ...
|
||||
port = 465
|
||||
receivers = me@example.com
|
||||
@ -47,8 +47,8 @@ How to generate index page
|
||||
target = html
|
||||
|
||||
[html]
|
||||
path = ${repository:root}/repository/aur-clone/x86_64/index.html
|
||||
link_path = http://example.com/aur-clone/x86_64
|
||||
path = ${repository:root}/repository/aur/x86_64/index.html
|
||||
link_path = http://example.com/aur/x86_64
|
||||
|
||||
Having this configuration, the generated ``index.html`` will be also automatically synced to remote services (e.g. S3).
|
||||
|
||||
@ -106,7 +106,7 @@ How to post build report to telegram
|
||||
[telegram]
|
||||
api_key = aaAAbbBBccCC
|
||||
chat_id = @ahriman
|
||||
link_path = http://example.com/aur-clone/x86_64
|
||||
link_path = http://example.com/aur/x86_64
|
||||
|
||||
``${api_key}`` is the one sent by `@BotFather <https://t.me/botfather>`__, ``${chat_id}`` is the value retrieved from previous step.
|
||||
|
||||
|
||||
@ -29,7 +29,7 @@ There are several choices:
|
||||
[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 (``Server = https://s3.eu-central-1.amazonaws.com/repository/aur-clone/x86_64``) or to GitHub (``Server = https://github.com/ahriman/repository/releases/download/aur-clone-x86_64``).
|
||||
After that just add ``/srv/repo`` to the ``pacman.conf`` as usual. You can also upload to S3 (``Server = https://s3.eu-central-1.amazonaws.com/repository/aur/x86_64``) or to GitHub (``Server = https://github.com/ahriman/repository/releases/download/aur-x86_64``).
|
||||
|
||||
How to sync to S3
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
@ -23,9 +23,9 @@ To 2.12.0
|
||||
|
||||
This release includes paths migration. Unlike usual case, no automatic migration is performed because it might break user configuration. The following noticeable changes have been made:
|
||||
|
||||
* Path to pre-built packages now includes repository name, i.e. it has been changed from ``/var/lib/ahriman/packages/x86_64`` to ``/var/lib/ahriman/packages/aur-clone/x86_64``.
|
||||
* Path to pacman databases now includes repository name too, it has been changed from ``/var/lib/ahriman/pacman/x86_64`` to ``/var/lib/ahriman/pacman/aur-clone/x86_64``.
|
||||
* Path to repository itself also includes repository name, from ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur-clone/x86_64``.
|
||||
* Path to pre-built packages now includes repository name, i.e. it has been changed from ``/var/lib/ahriman/packages/x86_64`` to ``/var/lib/ahriman/packages/aur/x86_64``.
|
||||
* Path to pacman databases now includes repository name too, it has been changed from ``/var/lib/ahriman/pacman/x86_64`` to ``/var/lib/ahriman/pacman/aur/x86_64``.
|
||||
* Path to repository itself also includes repository name, from ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur/x86_64``.
|
||||
|
||||
In order to migrate to the new filesystem tree the following actions are required:
|
||||
|
||||
@ -41,16 +41,16 @@ In order to migrate to the new filesystem tree the following actions are require
|
||||
Create directory tree. It can be done by running ``ahriman service-tree-migrate`` subcommand. It performs copying between the old repository tree and the new one. Alternatively directories can be copied by hands.
|
||||
|
||||
#.
|
||||
Edit configuration in case if anything is pointing to the old path, e.g. HTML report generation, in the way in which it will point to the directory inside repository specific one, e.g. ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur-clone/x86_64``.
|
||||
Edit configuration in case if anything is pointing to the old path, e.g. HTML report generation, in the way in which it will point to the directory inside repository specific one, e.g. ``/var/lib/ahriman/repository/x86_64`` to ``/var/lib/ahriman/repository/aur/x86_64``.
|
||||
|
||||
#.
|
||||
Run setup command (i.e. ``ahriman service-setup``) again with the same arguments as used before. This step can be done manually by editing devtools pacman configuration (``/usr/share/devtools/pacman.conf.d/ahriman-x86_64.conf`` by default) replacing ``Server`` with path to the repository, e.g.:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[aur-clone]
|
||||
[aur]
|
||||
SigLevel = Optional TrustAll
|
||||
Server = file:///var/lib/ahriman/repository/aur-clone/x86_64
|
||||
Server = file:///var/lib/ahriman/repository/aur/x86_64
|
||||
|
||||
In case of manual interventions make sure to remove architecture reference from ``web`` sections (if any) to avoid ambiguity.
|
||||
|
||||
@ -58,9 +58,9 @@ In order to migrate to the new filesystem tree the following actions are require
|
||||
Make sure to update remote synchronization services if any. Almost all of them rely on current repository tree by default, so it is required to setup either redirects or configure to synchronize to the old locations (e.g. ``object_path`` option for S3 synchronization).
|
||||
|
||||
#.
|
||||
Enable and start services again. Unit template parameter should include both repository architecture and name, dash separated, e.g. ``x86_64-aur-clone``, where ``x86_64`` is the repository architecture and ``aur-clone`` is the repository name:
|
||||
Enable and start services again. Unit template parameter should include both repository architecture and name, dash separated, e.g. ``x86_64-aur``, where ``x86_64`` is the repository architecture and ``aur`` is the repository name:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo systemctl enable --now ahriman@x86_64-aur-clone.timer
|
||||
sudo systemctl enable --now ahriman@x86_64-aur.timer
|
||||
sudo systemctl enable --now ahriman-web
|
||||
|
||||
@ -10,7 +10,7 @@ Initial setup
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
sudo ahriman -a x86_64 -r aur-clone service-setup ...
|
||||
sudo ahriman -a x86_64 -r aur service-setup ...
|
||||
|
||||
``service-setup`` literally does the following steps:
|
||||
|
||||
@ -19,7 +19,7 @@ Initial setup
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
echo 'PACKAGER="John Doe <john@doe.com>"' | sudo -u ahriman tee -a /var/lib/ahriman/.makepkg.conf
|
||||
echo 'PACKAGER="ahriman bot <ahriman@example.com>"' | sudo -u ahriman tee -a /var/lib/ahriman/.makepkg.conf
|
||||
|
||||
#.
|
||||
Configure build tools (it is required for correct dependency management system):
|
||||
@ -29,26 +29,26 @@ Initial setup
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
ln -s /usr/bin/archbuild /usr/local/bin/aur-clone-x86_64-build
|
||||
ln -s /usr/bin/archbuild /usr/local/bin/aur-x86_64-build
|
||||
|
||||
#.
|
||||
Create configuration file (same as previous ``{name}.conf``):
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
cp /usr/share/devtools/pacman.conf.d/{extra,aur-clone}.conf
|
||||
cp /usr/share/devtools/pacman.conf.d/{extra,aur}.conf
|
||||
|
||||
#.
|
||||
Change configuration file, add your own repository, add multilib repository etc:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
echo '[multilib]' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
|
||||
echo 'Include = /etc/pacman.d/mirrorlist' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
|
||||
echo '[multilib]' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
|
||||
echo 'Include = /etc/pacman.d/mirrorlist' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
|
||||
|
||||
echo '[aur-clone]' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
|
||||
echo 'SigLevel = Optional TrustAll' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
|
||||
echo 'Server = file:///var/lib/ahriman/repository/$repo/$arch' | tee -a /usr/share/devtools/pacman.conf.d/aur-clone-x86_64.conf
|
||||
echo '[aur]' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
|
||||
echo 'SigLevel = Optional TrustAll' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
|
||||
echo 'Server = file:///var/lib/ahriman/repository/$repo/$arch' | tee -a /usr/share/devtools/pacman.conf.d/aur-x86_64.conf
|
||||
|
||||
#.
|
||||
Set ``build_command`` option to point to your command:
|
||||
@ -56,14 +56,14 @@ Initial setup
|
||||
.. code-block:: shell
|
||||
|
||||
echo '[build]' | tee -a /etc/ahriman.ini.d/build.ini
|
||||
echo 'build_command = aur-clone-x86_64-build' | tee -a /etc/ahriman.ini.d/build.ini
|
||||
echo 'build_command = aur-x86_64-build' | tee -a /etc/ahriman.ini.d/build.ini
|
||||
|
||||
#.
|
||||
Configure ``/etc/sudoers.d/ahriman`` to allow running command without a password:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
echo 'Cmnd_Alias CARCHBUILD_CMD = /usr/local/bin/aur-clone-x86_64-build *' | tee -a /etc/sudoers.d/ahriman
|
||||
echo 'Cmnd_Alias CARCHBUILD_CMD = /usr/local/bin/aur-x86_64-build *' | tee -a /etc/sudoers.d/ahriman
|
||||
echo 'ahriman ALL=(ALL) NOPASSWD:SETENV: CARCHBUILD_CMD' | tee -a /etc/sudoers.d/ahriman
|
||||
chmod 400 /etc/sudoers.d/ahriman
|
||||
|
||||
@ -74,7 +74,7 @@ Initial setup
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
systemctl enable --now ahriman@x86_64-aur-clone.timer
|
||||
systemctl enable --now ahriman@x86_64-aur.timer
|
||||
|
||||
#.
|
||||
Start and enable status page:
|
||||
|
||||
Reference in New Issue
Block a user