docs: add comments to configuration

docs/configuration.rst

@@ -39,9 +39,9 @@ It will check current settings on common errors and compare configuration with k
 
 Base configuration settings.
 
-* ``apply_migrations`` - perform migrations on application start, boolean, optional, default ``yes``. Useful if you are using git version. Note, however, that this option must be changed only if you know what to do and going to handle migrations manually.
+* ``apply_migrations`` - perform database migrations on the application start, boolean, optional, default ``yes``. Useful if you are using git version. Note, however, that this option must be changed only if you know what to do and going to handle migrations manually.
-* ``database`` - path to SQLite database, string, required.
+* ``database`` - path to the application SQLite database, string, required.
-* ``include`` - path to directory with configuration files overrides, string, optional.
+* ``include`` - path to directory with configuration files overrides, string, optional. Files will be read in alphabetical order.
 * ``logging`` - path to logging configuration, string, required. Check ``logging.ini`` for reference.
 
 ``alpm:*`` groups
@@ -51,9 +51,9 @@ libalpm and AUR related configuration. Group name can refer to architecture, e.g
 
 * ``database`` - path to pacman system database cache, string, required.
 * ``mirror`` - package database mirror used by pacman for synchronization, string, required. This option supports standard pacman substitutions with ``$arch`` and ``$repo``. Note that the mentioned mirror should contain all repositories which are set by ``alpm.repositories`` option.
-* ``repositories`` - list of pacman repositories, space separated list of strings, required.
+* ``repositories`` - list of pacman repositories, used for package search, space separated list of strings, required.
-* ``root`` - root for alpm library, string, required.
+* ``root`` - root for alpm library, string, required. In the most cases it must point to the system root.
-* ``use_ahriman_cache`` - use local pacman package cache instead of system one, boolean, required. With this option enabled you might want to refresh database periodically (available as additional flag for some subcommands).
+* ``use_ahriman_cache`` - use local pacman package cache instead of system one, boolean, required. With this option enabled you might want to refresh database periodically (available as additional flag for some subcommands). If set to ``no``, databases must be synchronized manually.
 
 ``auth`` group
 --------------
@@ -64,7 +64,7 @@ Base authorization settings. ``OAuth`` provider requires ``aioauth-client`` libr
 * ``allow_read_only`` - allow requesting status APIs without authorization, boolean, required.
 * ``client_id`` - OAuth2 application client ID, string, required in case if ``oauth`` is used.
 * ``client_secret`` - OAuth2 application client secret key, string, required in case if ``oauth`` is used.
-* ``cookie_secret_key`` - secret key which will be used for cookies encryption, string, optional. It must be 32 URL-safe base64-encoded bytes and can be generated as following ``base64.urlsafe_b64encode(os.urandom(32)).decode("utf8")``. If not set, it will be generated automatically; note, however, that in this case, all sessions will be automatically invalidated during the service restart.
+* ``cookie_secret_key`` - secret key which will be used for cookies encryption, string, optional. It must be 32 bytes URL-safe base64-encoded and can be generated as following ``base64.urlsafe_b64encode(os.urandom(32)).decode("utf8")``. If not set, it will be generated automatically; note, however, that in this case, all sessions will be automatically invalidated during the service restart.
 * ``max_age`` - parameter which controls both cookie expiration and token expiration inside the service in seconds, integer, optional, default is 7 days.
 * ``oauth_icon`` - OAuth2 login button icon, string, optional, default is ``google``. Must be valid `Bootstrap icon <https://icons.getbootstrap.com/>`__ name.
 * ``oauth_provider`` - OAuth2 provider class name as is in ``aioauth-client`` (e.g. ``GoogleClient``, ``GithubClient`` etc), string, required in case if ``oauth`` is used.
@@ -148,7 +148,7 @@ Keyring generator plugin
 * ``homepage`` - URL to homepage location if any, string, optional.
 * ``license`` - list of licenses which are applied to this package, space separated list of strings, optional, default is ``Unlicense``.
 * ``package`` - keyring package name, string, optional, default is ``repo-keyring``, where ``repo`` is the repository name.
-* ``packagers`` - list of packagers keys, space separated list of strings, optional, if not set, the ``key_*`` options from ``sign`` group will be used.
+* ``packagers`` - list of packagers keys, space separated list of strings, optional, if not set, the user keys from database will be used.
 * ``revoked`` - list of revoked packagers keys, space separated list of strings, optional.
 * ``trusted`` - list of master keys, space separated list of strings, optional, if not set, the ``key`` option from ``sign`` group will be used.
 

package/share/ahriman/settings/ahriman.ini

@@ -1,85 +1,352 @@
 [settings]
+; Relative path to directory with configuration files overrides. Overrides will be applied in alphabetic order.
 include = ahriman.ini.d
+; Relative path to configuration used by logging package.
 logging = ahriman.ini.d/logging.ini
-apply_migrations = yes
+; Perform database migrations on the application start. Do not touch this option unless you know what are you doing.
+;apply_migrations = yes
+; Path to the application SQLite database.
 database = /var/lib/ahriman/ahriman.db
 
 [alpm]
+; Path to pacman system database cache.
 database = /var/lib/pacman
+; Arch linux mirror used by local pacman for synchronization.
 mirror = https://geo.mirror.pkgbuild.com/$repo/os/$arch
+; Space separated list of pacman repositories to search for packages.
 repositories = core extra multilib
+; Pacman's root directory. In the most cases it must point to the system root.
 root = /
+; Use local packages cache. If this option is enabled, the service will be able to synchronize databases (available
+; as additional option for some subcommands). If set to no, databases must be synchronized manually.
 use_ahriman_cache = yes
 
 [auth]
+; Authentication provider, must be one of disabled, configuration, oauth.
 target = disabled
-max_age = 604800
+; Allow read-only endpoint to be called without authentication.
-oauth_provider = GoogleClient
-oauth_scopes = https://www.googleapis.com/auth/userinfo.email
 allow_read_only = yes
+; OAuth2 application client ID and secret. Required if oauth is used.
+;client_id =
+;client_secret =
+; Cookie secret key to be used for cookies encryption. Must be valid 32 bytes URL-safe base64-encoded string.
+; If not set, it will be generated automatically.
+;cookie_secret_key =
+; Authentication cookie expiration in seconds.
+;max_age = 604800
+; OAuth2 provider icon for the web interface.
+;oauth_icon = google
+; OAuth2 provider class name, one of provided by aioauth-client. Required if oauth is used.
+;oauth_provider = GoogleClient
+; Scopes list for OAuth2 provider. Required if oauth is used.
+;oauth_scopes = https://www.googleapis.com/auth/userinfo.email
+; Optional password salt.
+;salt =
 
 [build]
-archbuild_flags =
+; List of additional flags passed to archbuild command.
-ignore_packages =
+;archbuild_flags =
-makechrootpkg_flags =
+; List of packages to be ignored during automatic updates.
+;ignore_packages =
+; List of additional flags passed to makechrootpkg command.
+;makechrootpkg_flags =
+; List of additional flags passed to makepkg command.
 makepkg_flags = --nocolor --ignorearch
+; List of enabled triggers in the order of calls.
 triggers = ahriman.core.gitremote.RemotePullTrigger ahriman.core.report.ReportTrigger ahriman.core.upload.UploadTrigger ahriman.core.gitremote.RemotePushTrigger
+; List of well-known triggers. Used only for configuration purposes.
 triggers_known = ahriman.core.distributed.WorkerLoaderTrigger ahriman.core.distributed.WorkerRegisterTrigger ahriman.core.distributed.WorkerTrigger ahriman.core.distributed.WorkerUnregisterTrigger ahriman.core.gitremote.RemotePullTrigger ahriman.core.gitremote.RemotePushTrigger ahriman.core.report.ReportTrigger ahriman.core.upload.UploadTrigger ahriman.core.support.KeyringTrigger ahriman.core.support.MirrorlistTrigger
-vcs_allowed_age = 604800
+; Maximal age in seconds of the VCS packages before their version will be updated with its remote source.
+;vcs_allowed_age = 604800
+; List of worker nodes addresses used for build process, e.g.:
+;     workers = http://10.0.0.1:8080 http://10.0.0.3:8080
+; Empty list means run on the local instance.
+;workers =
 
 [repository]
+; Application root.
 root = /var/lib/ahriman
 
 [sign]
+; Enable repository or package signing. Must be one of repository, package.
 target =
-
+; PGP key used for signing as default.
-[keyring]
+;key =
-target =
-
-[mirrorlist]
-target =
-
-[remote-pull]
-target =
-
-[remote-push]
-target =
-
-[report]
-target = console
-
-[console]
-use_utf = yes
-
-[email]
-no_empty_report = yes
-template = email-index.jinja2
-templates = /usr/share/ahriman/templates
-ssl = disabled
-
-[html]
-template = repo-index.jinja2
-templates = /usr/share/ahriman/templates
 
 [status]
+; Global switch to enable or disable status reporting.
 enabled = yes
+; Address of the remote service, e.g.:
+;     address = http://1.0.0.1:8080
+; In case if unix sockets are used, it might point to the valid socket with encoded path, e.g.:
+;     address = http+unix://%2Fvar%2Flib%2Fahriman%2Fsocket
+;address =
+; Optional password for authentication (if enabled).
+;password =
+; Do not log HTTP errors if occurs.
 suppress_http_log_errors = yes
-
+; HTTP request timeout in seconds.
-[telegram]
+;timeout = 30
-template = telegram-index.jinja2
+; Optional username for authentication (if enabled).
-templates = /usr/share/ahriman/templates
+;username =
-
-[upload]
-target =
-
-[rsync]
-command = rsync --archive --compress --partial --delete
-
-[s3]
-chunk_size = 8388608
 
 [web]
+; External address of the web service. Will be used for some features like OAuth. If none set will be generated as
+;     address = http://web.host:web.port
+;address =
+; Enable file upload endpoint used by some triggers.
+;enable_archive_upload = no
+; Address to bind the server.
 host = 127.0.0.1
+; Full URL to the repository index page used by templates.
+;index_url =
+; Max file size in bytes which can be uploaded to the server.
+;max_body_size =
+; Port to listen. Must be set, if the web service is enabled.
+;port =
+; Disable status (e.g. package status, logs, etc) endpoints. Useful for build only modes.
+;service_only = no
+; Path to directory with static files.
 static_path = /usr/share/ahriman/templates/static
+; List of directories with templates.
 templates = /usr/share/ahriman/templates
-unix_socket_unsafe = yes
+; Path to unix socket. If none set, unix socket will be disabled.
+;unix_socket =
+; Allow unix socket to be world readable.
+;unix_socket_unsafe = yes
+; Maximum amount of time in seconds to be waited before lock will be free, used by spawned processes (0 is infinite).
+;wait_timeout =
+
+[keyring]
+; List of configuration section names for keyring generator plugin, e.g.:
+;     target = keyring-trigger
+target =
+
+; Keyring generator trigger sample.
+;[keyring-trigger]
+; Generator type name.
+;type = keyring-generator
+; Optional keyring package description.
+;description=
+; Optional URL to the repository homepage.
+;homepage=
+; Keyring package licenses list.
+;license = Unlicense
+; Optional keyring package name.
+;package =
+; Optional packager PGP keys list. If none set, it will read from database.
+;packagers =
+; List of revoked PGP keys.
+;revoked =
+; List of master PGP keys. If none set, the sign.key value will be used.
+;trusted =
+
+[mirrorlist]
+; List of configuration section names for mirrorlist generator plugin, e.g.:
+;     target = mirrorlist-trigger
+target =
+
+; Mirror list generator trigger sample.
+;[mirrorlist-trigger]
+; Generator type name.
+;type = mirrorlist-generator
+; Optional mirrorlist package description.
+;description=
+; Optional URL to the repository homepage.
+;homepage=
+; Mirrorlist package licenses list.
+;license = Unlicense
+; Optional mirrorlist package name.
+;package =
+; Absolute path to generated mirrorlist file, usually path inside /etc/pacman.d directory.
+;path =
+; List of repository mirrors.
+;servers =
+
+[remote-pull]
+; List of configuration section names for git remote pull plugin, e.g.:
+;     target = remote-pull-trigger
+target =
+
+; git remote pull trigger sample.
+;[remote-pull-trigger]
+; Valid URL to pull repository, e.g.:
+;     pull_url = https://github.com/arcan1s/arcanisrepo.git
+;pull_url =
+; Remote branch to pull.
+;pull_branch = master
+
+[remote-push]
+; List of configuration section names for git remote push plugin, e.g.:
+;     target = remote-push-trigger
+target =
+
+; git remote push trigger sample.
+;[remote-push-trigger]
+; Author commit email.
+;commit_email = ahriman@localhost
+; Author commit user.
+;commit_user = ahriman
+; Valid URL to push repository, e.g.:
+;     push_url = https://key:token@github.com/arcan1s/arcanisrepo.git
+; Note, that more likely authentication must be enabled.
+;push_url =
+; Remote branch to push.
+;push_branch = master
+
+[report]
+; List of configuration section names for reporting plugin.
+target = console
+
+; Console reporting trigger configuration sample.
+[console]
+; Trigger type name
+;type = console
+; Use utf8 symbols in output.
+use_utf = yes
+
+; Email reporting trigger configuration sample.
+[email]
+; Trigger type name
+;type = email
+; Optional URL to the repository homepage.
+;homepage=
+; SMTP server address.
+;host =
+; Prefix for packages links. Link to a package will be formed as link_path / filename.
+;link_path =
+; Skip report generation if no packages were updated.
+;no_empty_report = yes
+; SMTP password.
+;password =
+; SMTP server port.
+;port =
+; List of emails to receive the reports.
+;receivers =
+; Sender email.
+;sender =
+; SMTP server SSL mode, one of ssl, starttls, disabled.
+;ssl = disabled
+; Template name to be used.
+template = email-index.jinja2
+; Template name to be used for full packages list generation (same as HTML report).
+;template_full =
+; List of directories with templates.
+templates = /usr/share/ahriman/templates
+; SMTP user.
+;user =
+
+; HTML reporting trigger configuration sample.
+[html]
+; Trigger type name
+;type = html
+; Optional URL to the repository homepage.
+;homepage=
+; Prefix for packages links. Link to a package will be formed as link_path / filename.
+;link_path =
+; Output path for the HTML report.
+;path =
+; Template name to be used.
+template = repo-index.jinja2
+; List of directories with templates.
+templates = /usr/share/ahriman/templates
+
+; Remote service callback trigger configuration sample.
+[remote-call]
+; Trigger type name
+;type = remote-call
+; Call for AUR packages update.
+;aur = no
+; Call for local packages update.
+;local = no
+; Call for manual packages update.
+;manual = no
+; Wait until remote process will be terminated in seconds.
+;wait_timeout = -1
+
+; Telegram reporting trigger configuration sample.
+[telegram]
+; Trigger type name
+;type = telegram
+; Telegram bot API key.
+;api_key =
+; Telegram chat ID.
+;chat_id =
+; Optional URL to the repository homepage.
+;homepage=
+; Prefix for packages links. Link to a package will be formed as link_path / filename.
+;link_path =
+; Template name to be used.
+template = telegram-index.jinja2
+; Telegram specific template mode, one of MarkdownV2, HTML or Markdown.
+;template_type = HTML
+; List of directories with templates.
+templates = /usr/share/ahriman/templates
+; HTTP request timeout in seconds.
+;timeout = 30
+
+[upload]
+; List of configuration section names for remote upload plugin, e.g.:
+;     target = rsync s3
+target =
+
+; GitHub upload trigger configuration sample.
+[github]
+; Trigger type name
+;type = github
+; GitHub repository owner username.
+;owner =
+; GitHub API key. public_repo (repo) scope is required.
+;password =
+; GitHub repository name.
+;repository =
+; HTTP request timeout in seconds.
+;timeout = 30
+; Include repository name to release name (recommended).
+;use_full_release_name = no
+; GitHub authentication username.
+;username =
+
+; Remote instance upload trigger configuration sample.
+[remote-service]
+; Trigger type name
+;type = remote-service
+; HTTP request timeout in seconds.
+;timeout = 30
+
+; rsync upload trigger configuration sample.
+[rsync]
+; Trigger type name
+;type = rsync
+; rsync command to run.
+command = rsync --archive --compress --partial --delete
+; Remote address and directory to sync, e.g.:
+;     remote = ahriman@10.0.0.1:/srv/repo
+;remote =
+
+; S3 upload trigger configuration sample.
+[s3]
+; Trigger type name
+;type = s3
+; AWS services access key.
+;access_key =
+; AWS S3 bucket name.
+;bucket =
+; Chunk size tp calculate ETags. Do not edit this value.
+;chunk_size = 8388608
+; Optional path prefix for stored objects.
+;object_path =
+; AWS S3 bucket region.
+;region =
+; AWS services secret key.
+;secret_key =
+
+; Remote worker configuration sample.
+;[worker]
+; Remotely reachable address of this instance, e.g.:
+;     address = http://10.0.0.1:8080
+;address =
+; Unique identifier of this instance if any.
+;identifier =
+; Maximum amount of time in seconds after which worker will be considered offline in case of no reports.
+;time_to_live = 60