diff options
| author | pennae <github@quasiparticle.net> | 2023-01-25 00:33:40 +0100 |
|---|---|---|
| committer | pennae <github@quasiparticle.net> | 2023-01-27 20:07:34 +0100 |
| commit | 0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9 (patch) | |
| tree | 6e28cb9ba90a3d03d6efab999b958527af45f84c /nixos/modules/services/web-apps | |
| parent | 8b8670db100efed03a979f7ec24c353f72c0bdbd (diff) | |
| download | nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.tar nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.tar.gz nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.tar.bz2 nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.tar.lz nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.tar.xz nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.tar.zst nixpkgs-0a6e6cf7e698a6a08a62d8863e2c66b36d5db0d9.zip | |
nixos/manual: render module chapters with nixos-render-docs
this converts meta.doc into an md pointer, not an xml pointer. since we no longer need xml for manual chapters we can also remove support for manual chapters from md-to-db.sh since pandoc converts smart quotes to docbook quote elements and our nixos-render-docs does not we lose this distinction in the rendered output. that's probably not that bad, our stylesheet didn't make use of this anyway (and pre-23.05 versions of the chapters didn't use quote elements either). also updates the nixpkgs manual to clarify that option docs support all extensions (although it doesn't support headings at all, so heading anchors don't work by extension).
Diffstat (limited to 'nixos/modules/services/web-apps')
20 files changed, 10 insertions, 1778 deletions
diff --git a/nixos/modules/services/web-apps/akkoma.nix b/nixos/modules/services/web-apps/akkoma.nix index 47ba53e4222..fc482ff32de 100644 --- a/nixos/modules/services/web-apps/akkoma.nix +++ b/nixos/modules/services/web-apps/akkoma.nix @@ -1082,5 +1082,5 @@ in { }; meta.maintainers = with maintainers; [ mvs ]; - meta.doc = ./akkoma.xml; + meta.doc = ./akkoma.md; } diff --git a/nixos/modules/services/web-apps/akkoma.xml b/nixos/modules/services/web-apps/akkoma.xml deleted file mode 100644 index 49cbcc911e1..00000000000 --- a/nixos/modules/services/web-apps/akkoma.xml +++ /dev/null @@ -1,398 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-akkoma"> - <title>Akkoma</title> - <para> - <link xlink:href="https://akkoma.dev/">Akkoma</link> is a - lightweight ActivityPub microblogging server forked from Pleroma. - </para> - <section xml:id="modules-services-akkoma-service-configuration"> - <title>Service configuration</title> - <para> - The Elixir configuration file required by Akkoma is generated - automatically from - <link xlink:href="options.html#opt-services.akkoma.config"><option>services.akkoma.config</option></link>. - Secrets must be included from external files outside of the Nix - store by setting the configuration option to an attribute set - containing the attribute <option>_secret</option> – a string - pointing to the file containing the actual value of the option. - </para> - <para> - For the mandatory configuration settings these secrets will be - generated automatically if the referenced file does not exist - during startup, unless disabled through - <link xlink:href="options.html#opt-services.akkoma.initSecrets"><option>services.akkoma.initSecrets</option></link>. - </para> - <para> - The following configuration binds Akkoma to the Unix socket - <literal>/run/akkoma/socket</literal>, expecting to be run behind - a HTTP proxy on <literal>fediverse.example.com</literal>. - </para> - <programlisting language="nix"> -services.akkoma.enable = true; -services.akkoma.config = { - ":pleroma" = { - ":instance" = { - name = "My Akkoma instance"; - description = "More detailed description"; - email = "admin@example.com"; - registration_open = false; - }; - - "Pleroma.Web.Endpoint" = { - url.host = "fediverse.example.com"; - }; - }; -}; -</programlisting> - <para> - Please refer to the - <link xlink:href="https://docs.akkoma.dev/stable/configuration/cheatsheet/">configuration - cheat sheet</link> for additional configuration options. - </para> - </section> - <section xml:id="modules-services-akkoma-user-management"> - <title>User management</title> - <para> - After the Akkoma service is running, the administration utility - can be used to - <link xlink:href="https://docs.akkoma.dev/stable/administration/CLI_tasks/user/">manage - users</link>. In particular an administrative user can be created - with - </para> - <programlisting> -$ pleroma_ctl user new <nickname> <email> --admin --moderator --password <password> -</programlisting> - </section> - <section xml:id="modules-services-akkoma-proxy-configuration"> - <title>Proxy configuration</title> - <para> - Although it is possible to expose Akkoma directly, it is common - practice to operate it behind an HTTP reverse proxy such as nginx. - </para> - <programlisting language="nix"> -services.akkoma.nginx = { - enableACME = true; - forceSSL = true; -}; - -services.nginx = { - enable = true; - - clientMaxBodySize = "16m"; - recommendedTlsSettings = true; - recommendedOptimisation = true; - recommendedGzipSettings = true; -}; -</programlisting> - <para> - Please refer to <xref linkend="module-security-acme" /> for - details on how to provision an SSL/TLS certificate. - </para> - <section xml:id="modules-services-akkoma-media-proxy"> - <title>Media proxy</title> - <para> - Without the media proxy function, Akkoma does not store any - remote media like pictures or video locally, and clients have to - fetch them directly from the source server. - </para> - <programlisting language="nix"> -# Enable nginx slice module distributed with Tengine -services.nginx.package = pkgs.tengine; - -# Enable media proxy -services.akkoma.config.":pleroma".":media_proxy" = { - enabled = true; - proxy_opts.redirect_on_failure = true; -}; - -# Adjust the persistent cache size as needed: -# Assuming an average object size of 128 KiB, around 1 MiB -# of memory is required for the key zone per GiB of cache. -# Ensure that the cache directory exists and is writable by nginx. -services.nginx.commonHttpConfig = '' - proxy_cache_path /var/cache/nginx/cache/akkoma-media-cache - levels= keys_zone=akkoma_media_cache:16m max_size=16g - inactive=1y use_temp_path=off; -''; - -services.akkoma.nginx = { - locations."/proxy" = { - proxyPass = "http://unix:/run/akkoma/socket"; - - extraConfig = '' - proxy_cache akkoma_media_cache; - - # Cache objects in slices of 1 MiB - slice 1m; - proxy_cache_key $host$uri$is_args$args$slice_range; - proxy_set_header Range $slice_range; - - # Decouple proxy and upstream responses - proxy_buffering on; - proxy_cache_lock on; - proxy_ignore_client_abort on; - - # Default cache times for various responses - proxy_cache_valid 200 1y; - proxy_cache_valid 206 301 304 1h; - - # Allow serving of stale items - proxy_cache_use_stale error timeout invalid_header updating; - ''; - }; -}; -</programlisting> - <section xml:id="modules-services-akkoma-prefetch-remote-media"> - <title>Prefetch remote media</title> - <para> - The following example enables the - <literal>MediaProxyWarmingPolicy</literal> MRF policy which - automatically fetches all media associated with a post through - the media proxy, as soon as the post is received by the - instance. - </para> - <programlisting language="nix"> -services.akkoma.config.":pleroma".":mrf".policies = - map (pkgs.formats.elixirConf { }).lib.mkRaw [ - "Pleroma.Web.ActivityPub.MRF.MediaProxyWarmingPolicy" -]; -</programlisting> - </section> - <section xml:id="modules-services-akkoma-media-previews"> - <title>Media previews</title> - <para> - Akkoma can generate previews for media. - </para> - <programlisting language="nix"> -services.akkoma.config.":pleroma".":media_preview_proxy" = { - enabled = true; - thumbnail_max_width = 1920; - thumbnail_max_height = 1080; -}; -</programlisting> - </section> - </section> - </section> - <section xml:id="modules-services-akkoma-frontend-management"> - <title>Frontend management</title> - <para> - Akkoma will be deployed with the <literal>pleroma-fe</literal> and - <literal>admin-fe</literal> frontends by default. These can be - modified by setting - <link xlink:href="options.html#opt-services.akkoma.frontends"><option>services.akkoma.frontends</option></link>. - </para> - <para> - The following example overrides the primary frontend’s default - configuration using a custom derivation. - </para> - <programlisting language="nix"> -services.akkoma.frontends.primary.package = pkgs.runCommand "pleroma-fe" { - config = builtins.toJSON { - expertLevel = 1; - collapseMessageWithSubject = false; - stopGifs = false; - replyVisibility = "following"; - webPushHideIfCW = true; - hideScopeNotice = true; - renderMisskeyMarkdown = false; - hideSiteFavicon = true; - postContentType = "text/markdown"; - showNavShortcuts = false; - }; - nativeBuildInputs = with pkgs; [ jq xorg.lndir ]; - passAsFile = [ "config" ]; -} '' - mkdir $out - lndir ${pkgs.akkoma-frontends.pleroma-fe} $out - - rm $out/static/config.json - jq -s add ${pkgs.akkoma-frontends.pleroma-fe}/static/config.json ${config} \ - >$out/static/config.json -''; -</programlisting> - </section> - <section xml:id="modules-services-akkoma-federation-policies"> - <title>Federation policies</title> - <para> - Akkoma comes with a number of modules to police federation with - other ActivityPub instances. The most valuable for typical users - is the - <link xlink:href="https://docs.akkoma.dev/stable/configuration/cheatsheet/#mrf_simple"><literal>:mrf_simple</literal></link> - module which allows limiting federation based on instance - hostnames. - </para> - <para> - This configuration snippet provides an example on how these can be - used. Choosing an adequate federation policy is not trivial and - entails finding a balance between connectivity to the rest of the - fediverse and providing a pleasant experience to the users of an - instance. - </para> - <programlisting language="nix"> -services.akkoma.config.":pleroma" = with (pkgs.formats.elixirConf { }).lib; { - ":mrf".policies = map mkRaw [ - "Pleroma.Web.ActivityPub.MRF.SimplePolicy" - ]; - - ":mrf_simple" = { - # Tag all media as sensitive - media_nsfw = mkMap { - "nsfw.weird.kinky" = "Untagged NSFW content"; - }; - - # Reject all activities except deletes - reject = mkMap { - "kiwifarms.cc" = "Persistent harassment of users, no moderation"; - }; - - # Force posts to be visible by followers only - followers_only = mkMap { - "beta.birdsite.live" = "Avoid polluting timelines with Twitter posts"; - }; - }; -}; -</programlisting> - </section> - <section xml:id="modules-services-akkoma-upload-filters"> - <title>Upload filters</title> - <para> - This example strips GPS and location metadata from uploads, - deduplicates them and anonymises the the file name. - </para> - <programlisting language="nix"> -services.akkoma.config.":pleroma"."Pleroma.Upload".filters = - map (pkgs.formats.elixirConf { }).lib.mkRaw [ - "Pleroma.Upload.Filter.Exiftool" - "Pleroma.Upload.Filter.Dedupe" - "Pleroma.Upload.Filter.AnonymizeFilename" - ]; -</programlisting> - </section> - <section xml:id="modules-services-akkoma-migration-pleroma"> - <title>Migration from Pleroma</title> - <para> - Pleroma instances can be migrated to Akkoma either by copying the - database and upload data or by pointing Akkoma to the existing - data. The necessary database migrations are run automatically - during startup of the service. - </para> - <para> - The configuration has to be copy‐edited manually. - </para> - <para> - Depending on the size of the database, the initial migration may - take a long time and exceed the startup timeout of the system - manager. To work around this issue one may adjust the startup - timeout - <option>systemd.services.akkoma.serviceConfig.TimeoutStartSec</option> - or simply run the migrations manually: - </para> - <programlisting> -pleroma_ctl migrate -</programlisting> - <section xml:id="modules-services-akkoma-migration-pleroma-copy"> - <title>Copying data</title> - <para> - Copying the Pleroma data instead of re‐using it in place may - permit easier reversion to Pleroma, but allows the two data sets - to diverge. - </para> - <para> - First disable Pleroma and then copy its database and upload - data: - </para> - <programlisting> -# Create a copy of the database -nix-shell -p postgresql --run 'createdb -T pleroma akkoma' - -# Copy upload data -mkdir /var/lib/akkoma -cp -R --reflink=auto /var/lib/pleroma/uploads /var/lib/akkoma/ -</programlisting> - <para> - After the data has been copied, enable the Akkoma service and - verify that the migration has been successful. If no longer - required, the original data may then be deleted: - </para> - <programlisting> -# Delete original database -nix-shell -p postgresql --run 'dropdb pleroma' - -# Delete original Pleroma state -rm -r /var/lib/pleroma -</programlisting> - </section> - <section xml:id="modules-services-akkoma-migration-pleroma-reuse"> - <title>Re‐using data</title> - <para> - To re‐use the Pleroma data in place, disable Pleroma and enable - Akkoma, pointing it to the Pleroma database and upload - directory. - </para> - <programlisting language="nix"> -# Adjust these settings according to the database name and upload directory path used by Pleroma -services.akkoma.config.":pleroma"."Pleroma.Repo".database = "pleroma"; -services.akkoma.config.":pleroma".":instance".upload_dir = "/var/lib/pleroma/uploads"; -</programlisting> - <para> - Please keep in mind that after the Akkoma service has been - started, any migrations applied by Akkoma have to be rolled back - before the database can be used again with Pleroma. This can be - achieved through <literal>pleroma_ctl ecto.rollback</literal>. - Refer to the - <link xlink:href="https://hexdocs.pm/ecto_sql/Mix.Tasks.Ecto.Rollback.html">Ecto - SQL documentation</link> for details. - </para> - </section> - </section> - <section xml:id="modules-services-akkoma-advanced-deployment"> - <title>Advanced deployment options</title> - <section xml:id="modules-services-akkoma-confinement"> - <title>Confinement</title> - <para> - The Akkoma systemd service may be confined to a chroot with - </para> - <programlisting language="nix"> -services.systemd.akkoma.confinement.enable = true; -</programlisting> - <para> - Confinement of services is not generally supported in NixOS and - therefore disabled by default. Depending on the Akkoma - configuration, the default confinement settings may be - insufficient and lead to subtle errors at run time, requiring - adjustment: - </para> - <para> - Use - <link xlink:href="options.html#opt-systemd.services._name_.confinement.packages"><option>services.systemd.akkoma.confinement.packages</option></link> - to make packages available in the chroot. - </para> - <para> - <option>services.systemd.akkoma.serviceConfig.BindPaths</option> - and - <option>services.systemd.akkoma.serviceConfig.BindReadOnlyPaths</option> - permit access to outside paths through bind mounts. Refer to - <link xlink:href="https://www.freedesktop.org/software/systemd/man/systemd.exec.html#BindPaths="><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></link> - for details. - </para> - </section> - <section xml:id="modules-services-akkoma-distributed-deployment"> - <title>Distributed deployment</title> - <para> - Being an Elixir application, Akkoma can be deployed in a - distributed fashion. - </para> - <para> - This requires setting - <link xlink:href="options.html#opt-services.akkoma.dist.address"><option>services.akkoma.dist.address</option></link> - and - <link xlink:href="options.html#opt-services.akkoma.dist.cookie"><option>services.akkoma.dist.cookie</option></link>. - The specifics depend strongly on the deployment environment. For - more information please check the relevant - <link xlink:href="https://www.erlang.org/doc/reference_manual/distributed.html">Erlang - documentation</link>. - </para> - </section> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/discourse.nix b/nixos/modules/services/web-apps/discourse.nix index b8104ade467..5565a4f45d1 100644 --- a/nixos/modules/services/web-apps/discourse.nix +++ b/nixos/modules/services/web-apps/discourse.nix @@ -1080,6 +1080,6 @@ in ]; }; - meta.doc = ./discourse.xml; + meta.doc = ./discourse.md; meta.maintainers = [ lib.maintainers.talyz ]; } diff --git a/nixos/modules/services/web-apps/discourse.xml b/nixos/modules/services/web-apps/discourse.xml deleted file mode 100644 index a5e8b3656b7..00000000000 --- a/nixos/modules/services/web-apps/discourse.xml +++ /dev/null @@ -1,331 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-discourse"> - <title>Discourse</title> - <para> - <link xlink:href="https://www.discourse.org/">Discourse</link> is a - modern and open source discussion platform. - </para> - <section xml:id="module-services-discourse-basic-usage"> - <title>Basic usage</title> - <para> - A minimal configuration using Let’s Encrypt for TLS certificates - looks like this: - </para> - <programlisting> -services.discourse = { - enable = true; - hostname = "discourse.example.com"; - admin = { - email = "admin@example.com"; - username = "admin"; - fullName = "Administrator"; - passwordFile = "/path/to/password_file"; - }; - secretKeyBaseFile = "/path/to/secret_key_base_file"; -}; -security.acme.email = "me@example.com"; -security.acme.acceptTerms = true; -</programlisting> - <para> - Provided a proper DNS setup, you’ll be able to connect to the - instance at <literal>discourse.example.com</literal> and log in - using the credentials provided in - <literal>services.discourse.admin</literal>. - </para> - </section> - <section xml:id="module-services-discourse-tls"> - <title>Using a regular TLS certificate</title> - <para> - To set up TLS using a regular certificate and key on file, use the - <xref linkend="opt-services.discourse.sslCertificate" /> and - <xref linkend="opt-services.discourse.sslCertificateKey" /> - options: - </para> - <programlisting> -services.discourse = { - enable = true; - hostname = "discourse.example.com"; - sslCertificate = "/path/to/ssl_certificate"; - sslCertificateKey = "/path/to/ssl_certificate_key"; - admin = { - email = "admin@example.com"; - username = "admin"; - fullName = "Administrator"; - passwordFile = "/path/to/password_file"; - }; - secretKeyBaseFile = "/path/to/secret_key_base_file"; -}; -</programlisting> - </section> - <section xml:id="module-services-discourse-database"> - <title>Database access</title> - <para> - Discourse uses PostgreSQL to store most of its data. A database - will automatically be enabled and a database and role created - unless <xref linkend="opt-services.discourse.database.host" /> is - changed from its default of <literal>null</literal> or - <xref linkend="opt-services.discourse.database.createLocally" /> - is set to <literal>false</literal>. - </para> - <para> - External database access can also be configured by setting - <xref linkend="opt-services.discourse.database.host" />, - <xref linkend="opt-services.discourse.database.username" /> and - <xref linkend="opt-services.discourse.database.passwordFile" /> as - appropriate. Note that you need to manually create a database - called <literal>discourse</literal> (or the name you chose in - <xref linkend="opt-services.discourse.database.name" />) and allow - the configured database user full access to it. - </para> - </section> - <section xml:id="module-services-discourse-mail"> - <title>Email</title> - <para> - In addition to the basic setup, you’ll want to configure an SMTP - server Discourse can use to send user registration and password - reset emails, among others. You can also optionally let Discourse - receive email, which enables people to reply to threads and - conversations via email. - </para> - <para> - A basic setup which assumes you want to use your configured - <link linkend="opt-services.discourse.hostname">hostname</link> as - email domain can be done like this: - </para> - <programlisting> -services.discourse = { - enable = true; - hostname = "discourse.example.com"; - sslCertificate = "/path/to/ssl_certificate"; - sslCertificateKey = "/path/to/ssl_certificate_key"; - admin = { - email = "admin@example.com"; - username = "admin"; - fullName = "Administrator"; - passwordFile = "/path/to/password_file"; - }; - mail.outgoing = { - serverAddress = "smtp.emailprovider.com"; - port = 587; - username = "user@emailprovider.com"; - passwordFile = "/path/to/smtp_password_file"; - }; - mail.incoming.enable = true; - secretKeyBaseFile = "/path/to/secret_key_base_file"; -}; -</programlisting> - <para> - This assumes you have set up an MX record for the address you’ve - set in - <link linkend="opt-services.discourse.hostname">hostname</link> - and requires proper SPF, DKIM and DMARC configuration to be done - for the domain you’re sending from, in order for email to be - reliably delivered. - </para> - <para> - If you want to use a different domain for your outgoing email (for - example <literal>example.com</literal> instead of - <literal>discourse.example.com</literal>) you should set - <xref linkend="opt-services.discourse.mail.notificationEmailAddress" /> - and - <xref linkend="opt-services.discourse.mail.contactEmailAddress" /> - manually. - </para> - <note> - <para> - Setup of TLS for incoming email is currently only configured - automatically when a regular TLS certificate is used, i.e. when - <xref linkend="opt-services.discourse.sslCertificate" /> and - <xref linkend="opt-services.discourse.sslCertificateKey" /> are - set. - </para> - </note> - </section> - <section xml:id="module-services-discourse-settings"> - <title>Additional settings</title> - <para> - Additional site settings and backend settings, for which no - explicit NixOS options are provided, can be set in - <xref linkend="opt-services.discourse.siteSettings" /> and - <xref linkend="opt-services.discourse.backendSettings" /> - respectively. - </para> - <section xml:id="module-services-discourse-site-settings"> - <title>Site settings</title> - <para> - <quote>Site settings</quote> are the settings that can be - changed through the Discourse UI. Their - <emphasis>default</emphasis> values can be set using - <xref linkend="opt-services.discourse.siteSettings" />. - </para> - <para> - Settings are expressed as a Nix attribute set which matches the - structure of the configuration in - <link xlink:href="https://github.com/discourse/discourse/blob/master/config/site_settings.yml">config/site_settings.yml</link>. - To find a setting’s path, you only need to care about the first - two levels; i.e. its category (e.g. <literal>login</literal>) - and name (e.g. <literal>invite_only</literal>). - </para> - <para> - Settings containing secret data should be set to an attribute - set containing the attribute <literal>_secret</literal> - a - string pointing to a file containing the value the option should - be set to. See the example. - </para> - </section> - <section xml:id="module-services-discourse-backend-settings"> - <title>Backend settings</title> - <para> - Settings are expressed as a Nix attribute set which matches the - structure of the configuration in - <link xlink:href="https://github.com/discourse/discourse/blob/stable/config/discourse_defaults.conf">config/discourse.conf</link>. - Empty parameters can be defined by setting them to - <literal>null</literal>. - </para> - </section> - <section xml:id="module-services-discourse-settings-example"> - <title>Example</title> - <para> - The following example sets the title and description of the - Discourse instance and enables GitHub login in the site - settings, and changes a few request limits in the backend - settings: - </para> - <programlisting> -services.discourse = { - enable = true; - hostname = "discourse.example.com"; - sslCertificate = "/path/to/ssl_certificate"; - sslCertificateKey = "/path/to/ssl_certificate_key"; - admin = { - email = "admin@example.com"; - username = "admin"; - fullName = "Administrator"; - passwordFile = "/path/to/password_file"; - }; - mail.outgoing = { - serverAddress = "smtp.emailprovider.com"; - port = 587; - username = "user@emailprovider.com"; - passwordFile = "/path/to/smtp_password_file"; - }; - mail.incoming.enable = true; - siteSettings = { - required = { - title = "My Cats"; - site_description = "Discuss My Cats (and be nice plz)"; - }; - login = { - enable_github_logins = true; - github_client_id = "a2f6dfe838cb3206ce20"; - github_client_secret._secret = /run/keys/discourse_github_client_secret; - }; - }; - backendSettings = { - max_reqs_per_ip_per_minute = 300; - max_reqs_per_ip_per_10_seconds = 60; - max_asset_reqs_per_ip_per_10_seconds = 250; - max_reqs_per_ip_mode = "warn+block"; - }; - secretKeyBaseFile = "/path/to/secret_key_base_file"; -}; -</programlisting> - <para> - In the resulting site settings file, the - <literal>login.github_client_secret</literal> key will be set to - the contents of the - <filename>/run/keys/discourse_github_client_secret</filename> - file. - </para> - </section> - </section> - <section xml:id="module-services-discourse-plugins"> - <title>Plugins</title> - <para> - You can install Discourse plugins using the - <xref linkend="opt-services.discourse.plugins" /> option. - Pre-packaged plugins are provided in - <literal><your_discourse_package_here>.plugins</literal>. If - you want the full suite of plugins provided through - <literal>nixpkgs</literal>, you can also set the - <xref linkend="opt-services.discourse.package" /> option to - <literal>pkgs.discourseAllPlugins</literal>. - </para> - <para> - Plugins can be built with the - <literal><your_discourse_package_here>.mkDiscoursePlugin</literal> - function. Normally, it should suffice to provide a - <literal>name</literal> and <literal>src</literal> attribute. If - the plugin has Ruby dependencies, however, they need to be - packaged in accordance with the - <link xlink:href="https://nixos.org/manual/nixpkgs/stable/#developing-with-ruby">Developing - with Ruby</link> section of the Nixpkgs manual and the appropriate - gem options set in <literal>bundlerEnvArgs</literal> (normally - <literal>gemdir</literal> is sufficient). A plugin’s Ruby - dependencies are listed in its <filename>plugin.rb</filename> file - as function calls to <literal>gem</literal>. To construct the - corresponding <filename>Gemfile</filename> manually, run - <command>bundle init</command>, then add the - <literal>gem</literal> lines to it verbatim. - </para> - <para> - Much of the packaging can be done automatically by the - <filename>nixpkgs/pkgs/servers/web-apps/discourse/update.py</filename> - script - just add the plugin to the <literal>plugins</literal> - list in the <literal>update_plugins</literal> function and run the - script: - </para> - <programlisting language="bash"> -./update.py update-plugins -</programlisting> - <para> - Some plugins provide - <link linkend="module-services-discourse-site-settings">site - settings</link>. Their defaults can be configured using - <xref linkend="opt-services.discourse.siteSettings" />, just like - regular site settings. To find the names of these settings, look - in the <literal>config/settings.yml</literal> file of the plugin - repo. - </para> - <para> - For example, to add the - <link xlink:href="https://github.com/discourse/discourse-spoiler-alert">discourse-spoiler-alert</link> - and - <link xlink:href="https://github.com/discourse/discourse-solved">discourse-solved</link> - plugins, and disable <literal>discourse-spoiler-alert</literal> by - default: - </para> - <programlisting> -services.discourse = { - enable = true; - hostname = "discourse.example.com"; - sslCertificate = "/path/to/ssl_certificate"; - sslCertificateKey = "/path/to/ssl_certificate_key"; - admin = { - email = "admin@example.com"; - username = "admin"; - fullName = "Administrator"; - passwordFile = "/path/to/password_file"; - }; - mail.outgoing = { - serverAddress = "smtp.emailprovider.com"; - port = 587; - username = "user@emailprovider.com"; - passwordFile = "/path/to/smtp_password_file"; - }; - mail.incoming.enable = true; - plugins = with config.services.discourse.package.plugins; [ - discourse-spoiler-alert - discourse-solved - ]; - siteSettings = { - plugins = { - spoiler_enabled = false; - }; - }; - secretKeyBaseFile = "/path/to/secret_key_base_file"; -}; -</programlisting> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/grocy.nix b/nixos/modules/services/web-apps/grocy.nix index 6efc2ccfd30..3bcda3caeda 100644 --- a/nixos/modules/services/web-apps/grocy.nix +++ b/nixos/modules/services/web-apps/grocy.nix @@ -167,6 +167,6 @@ in { meta = { maintainers = with maintainers; [ ma27 ]; - doc = ./grocy.xml; + doc = ./grocy.md; }; } diff --git a/nixos/modules/services/web-apps/grocy.xml b/nixos/modules/services/web-apps/grocy.xml deleted file mode 100644 index 08de25b4ce2..00000000000 --- a/nixos/modules/services/web-apps/grocy.xml +++ /dev/null @@ -1,84 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-grocy"> - <title>Grocy</title> - <para> - <link xlink:href="https://grocy.info/">Grocy</link> is a web-based - self-hosted groceries & household management solution for your - home. - </para> - <section xml:id="module-services-grocy-basic-usage"> - <title>Basic usage</title> - <para> - A very basic configuration may look like this: - </para> - <programlisting> -{ pkgs, ... }: -{ - services.grocy = { - enable = true; - hostName = "grocy.tld"; - }; -} -</programlisting> - <para> - This configures a simple vhost using - <link linkend="opt-services.nginx.enable">nginx</link> which - listens to <literal>grocy.tld</literal> with fully configured - ACME/LE (this can be disabled by setting - <link linkend="opt-services.grocy.nginx.enableSSL">services.grocy.nginx.enableSSL</link> - to <literal>false</literal>). After the initial setup the - credentials <literal>admin:admin</literal> can be used to login. - </para> - <para> - The application’s state is persisted at - <literal>/var/lib/grocy/grocy.db</literal> in a - <literal>sqlite3</literal> database. The migration is applied when - requesting the <literal>/</literal>-route of the application. - </para> - </section> - <section xml:id="module-services-grocy-settings"> - <title>Settings</title> - <para> - The configuration for <literal>grocy</literal> is located at - <literal>/etc/grocy/config.php</literal>. By default, the - following settings can be defined in the NixOS-configuration: - </para> - <programlisting> -{ pkgs, ... }: -{ - services.grocy.settings = { - # The default currency in the system for invoices etc. - # Please note that exchange rates aren't taken into account, this - # is just the setting for what's shown in the frontend. - currency = "EUR"; - - # The display language (and locale configuration) for grocy. - culture = "de"; - - calendar = { - # Whether or not to show the week-numbers - # in the calendar. - showWeekNumber = true; - - # Index of the first day to be shown in the calendar (0=Sunday, 1=Monday, - # 2=Tuesday and so on). - firstDayOfWeek = 2; - }; - }; -} -</programlisting> - <para> - If you want to alter the configuration file on your own, you can - do this manually with an expression like this: - </para> - <programlisting> -{ lib, ... }: -{ - environment.etc."grocy/config.php".text = lib.mkAfter '' - // Arbitrary PHP code in grocy's configuration file - ''; -} -</programlisting> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/jitsi-meet.nix b/nixos/modules/services/web-apps/jitsi-meet.nix index 5b0934b2fb7..28be3a3702e 100644 --- a/nixos/modules/services/web-apps/jitsi-meet.nix +++ b/nixos/modules/services/web-apps/jitsi-meet.nix @@ -451,6 +451,6 @@ in }; }; - meta.doc = ./jitsi-meet.xml; + meta.doc = ./jitsi-meet.md; meta.maintainers = lib.teams.jitsi.members; } diff --git a/nixos/modules/services/web-apps/jitsi-meet.xml b/nixos/modules/services/web-apps/jitsi-meet.xml deleted file mode 100644 index 4d2d8aa55e1..00000000000 --- a/nixos/modules/services/web-apps/jitsi-meet.xml +++ /dev/null @@ -1,55 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-jitsi-meet"> - <title>Jitsi Meet</title> - <para> - With Jitsi Meet on NixOS you can quickly configure a complete, - private, self-hosted video conferencing solution. - </para> - <section xml:id="module-services-jitsi-basic-usage"> - <title>Basic usage</title> - <para> - A minimal configuration using Let’s Encrypt for TLS certificates - looks like this: - </para> - <programlisting> -{ - services.jitsi-meet = { - enable = true; - hostName = "jitsi.example.com"; - }; - services.jitsi-videobridge.openFirewall = true; - networking.firewall.allowedTCPPorts = [ 80 443 ]; - security.acme.email = "me@example.com"; - security.acme.acceptTerms = true; -} -</programlisting> - </section> - <section xml:id="module-services-jitsi-configuration"> - <title>Configuration</title> - <para> - Here is the minimal configuration with additional configurations: - </para> - <programlisting> -{ - services.jitsi-meet = { - enable = true; - hostName = "jitsi.example.com"; - config = { - enableWelcomePage = false; - prejoinPageEnabled = true; - defaultLang = "fi"; - }; - interfaceConfig = { - SHOW_JITSI_WATERMARK = false; - SHOW_WATERMARK_FOR_GUESTS = false; - }; - }; - services.jitsi-videobridge.openFirewall = true; - networking.firewall.allowedTCPPorts = [ 80 443 ]; - security.acme.email = "me@example.com"; - security.acme.acceptTerms = true; -} -</programlisting> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/keycloak.nix b/nixos/modules/services/web-apps/keycloak.nix index d52190a2864..a7e4fab8ea2 100644 --- a/nixos/modules/services/web-apps/keycloak.nix +++ b/nixos/modules/services/web-apps/keycloak.nix @@ -674,6 +674,6 @@ in mkIf createLocalMySQL (mkDefault dbPkg); }; - meta.doc = ./keycloak.xml; + meta.doc = ./keycloak.md; meta.maintainers = [ maintainers.talyz ]; } diff --git a/nixos/modules/services/web-apps/keycloak.xml b/nixos/modules/services/web-apps/keycloak.xml deleted file mode 100644 index 148782d30f3..00000000000 --- a/nixos/modules/services/web-apps/keycloak.xml +++ /dev/null @@ -1,177 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-keycloak"> - <title>Keycloak</title> - <para> - <link xlink:href="https://www.keycloak.org/">Keycloak</link> is an - open source identity and access management server with support for - <link xlink:href="https://openid.net/connect/">OpenID - Connect</link>, <link xlink:href="https://oauth.net/2/">OAUTH - 2.0</link> and - <link xlink:href="https://en.wikipedia.org/wiki/SAML_2.0">SAML - 2.0</link>. - </para> - <section xml:id="module-services-keycloak-admin"> - <title>Administration</title> - <para> - An administrative user with the username <literal>admin</literal> - is automatically created in the <literal>master</literal> realm. - Its initial password can be configured by setting - <xref linkend="opt-services.keycloak.initialAdminPassword" /> and - defaults to <literal>changeme</literal>. The password is not - stored safely and should be changed immediately in the admin - panel. - </para> - <para> - Refer to the - <link xlink:href="https://www.keycloak.org/docs/latest/server_admin/index.html">Keycloak - Server Administration Guide</link> for information on how to - administer your Keycloak instance. - </para> - </section> - <section xml:id="module-services-keycloak-database"> - <title>Database access</title> - <para> - Keycloak can be used with either PostgreSQL, MariaDB or MySQL. - Which one is used can be configured in - <xref linkend="opt-services.keycloak.database.type" />. The - selected database will automatically be enabled and a database and - role created unless - <xref linkend="opt-services.keycloak.database.host" /> is changed - from its default of <literal>localhost</literal> or - <xref linkend="opt-services.keycloak.database.createLocally" /> is - set to <literal>false</literal>. - </para> - <para> - External database access can also be configured by setting - <xref linkend="opt-services.keycloak.database.host" />, - <xref linkend="opt-services.keycloak.database.name" />, - <xref linkend="opt-services.keycloak.database.username" />, - <xref linkend="opt-services.keycloak.database.useSSL" /> and - <xref linkend="opt-services.keycloak.database.caCert" /> as - appropriate. Note that you need to manually create the database - and allow the configured database user full access to it. - </para> - <para> - <xref linkend="opt-services.keycloak.database.passwordFile" /> - must be set to the path to a file containing the password used to - log in to the database. If - <xref linkend="opt-services.keycloak.database.host" /> and - <xref linkend="opt-services.keycloak.database.createLocally" /> - are kept at their defaults, the database role - <literal>keycloak</literal> with that password is provisioned on - the local database instance. - </para> - <warning> - <para> - The path should be provided as a string, not a Nix path, since - Nix paths are copied into the world readable Nix store. - </para> - </warning> - </section> - <section xml:id="module-services-keycloak-hostname"> - <title>Hostname</title> - <para> - The hostname is used to build the public URL used as base for all - frontend requests and must be configured through - <xref linkend="opt-services.keycloak.settings.hostname" />. - </para> - <note> - <para> - If you’re migrating an old Wildfly based Keycloak instance and - want to keep compatibility with your current clients, you’ll - likely want to set - <xref linkend="opt-services.keycloak.settings.http-relative-path" /> - to <literal>/auth</literal>. See the option description for more - details. - </para> - </note> - <para> - <xref linkend="opt-services.keycloak.settings.hostname-strict-backchannel" /> - determines whether Keycloak should force all requests to go - through the frontend URL. By default, Keycloak allows backend - requests to instead use its local hostname or IP address and may - also advertise it to clients through its OpenID Connect Discovery - endpoint. - </para> - <para> - For more information on hostname configuration, see the - <link xlink:href="https://www.keycloak.org/server/hostname">Hostname - section of the Keycloak Server Installation and Configuration - Guide</link>. - </para> - </section> - <section xml:id="module-services-keycloak-tls"> - <title>Setting up TLS/SSL</title> - <para> - By default, Keycloak won’t accept unsecured HTTP connections - originating from outside its local network. - </para> - <para> - HTTPS support requires a TLS/SSL certificate and a private key, - both - <link xlink:href="https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail">PEM - formatted</link>. Their paths should be set through - <xref linkend="opt-services.keycloak.sslCertificate" /> and - <xref linkend="opt-services.keycloak.sslCertificateKey" />. - </para> - <warning> - <para> - The paths should be provided as a strings, not a Nix paths, - since Nix paths are copied into the world readable Nix store. - </para> - </warning> - </section> - <section xml:id="module-services-keycloak-themes"> - <title>Themes</title> - <para> - You can package custom themes and make them visible to Keycloak - through <xref linkend="opt-services.keycloak.themes" />. See the - <link xlink:href="https://www.keycloak.org/docs/latest/server_development/#_themes">Themes - section of the Keycloak Server Development Guide</link> and the - description of the aforementioned NixOS option for more - information. - </para> - </section> - <section xml:id="module-services-keycloak-settings"> - <title>Configuration file settings</title> - <para> - Keycloak server configuration parameters can be set in - <xref linkend="opt-services.keycloak.settings" />. These - correspond directly to options in - <filename>conf/keycloak.conf</filename>. Some of the most - important parameters are documented as suboptions, the rest can be - found in the - <link xlink:href="https://www.keycloak.org/server/all-config">All - configuration section of the Keycloak Server Installation and - Configuration Guide</link>. - </para> - <para> - Options containing secret data should be set to an attribute set - containing the attribute <literal>_secret</literal> - a string - pointing to a file containing the value the option should be set - to. See the description of - <xref linkend="opt-services.keycloak.settings" /> for an example. - </para> - </section> - <section xml:id="module-services-keycloak-example-config"> - <title>Example configuration</title> - <para> - A basic configuration with some custom settings could look like - this: - </para> - <programlisting> -services.keycloak = { - enable = true; - settings = { - hostname = "keycloak.example.com"; - hostname-strict-backchannel = true; - }; - initialAdminPassword = "e6Wcm0RrtegMEHl"; # change on first login - sslCertificate = "/run/keys/ssl_cert"; - sslCertificateKey = "/run/keys/ssl_key"; - database.passwordFile = "/run/keys/db_password"; -}; -</programlisting> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/lemmy.nix b/nixos/modules/services/web-apps/lemmy.nix index f2eb6e726b9..af0fb38121a 100644 --- a/nixos/modules/services/web-apps/lemmy.nix +++ b/nixos/modules/services/web-apps/lemmy.nix @@ -6,7 +6,7 @@ let in { meta.maintainers = with maintainers; [ happysalada ]; - meta.doc = ./lemmy.xml; + meta.doc = ./lemmy.md; imports = [ (mkRemovedOptionModule [ "services" "lemmy" "jwtSecretPath" ] "As of v0.13.0, Lemmy auto-generates the JWT secret.") diff --git a/nixos/modules/services/web-apps/lemmy.xml b/nixos/modules/services/web-apps/lemmy.xml deleted file mode 100644 index 114e11f3488..00000000000 --- a/nixos/modules/services/web-apps/lemmy.xml +++ /dev/null @@ -1,53 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-lemmy"> - <title>Lemmy</title> - <para> - Lemmy is a federated alternative to reddit in rust. - </para> - <section xml:id="module-services-lemmy-quickstart"> - <title>Quickstart</title> - <para> - the minimum to start lemmy is - </para> - <programlisting language="nix"> -services.lemmy = { - enable = true; - settings = { - hostname = "lemmy.union.rocks"; - database.createLocally = true; - }; - caddy.enable = true; -} -</programlisting> - <para> - this will start the backend on port 8536 and the frontend on port - 1234. It will expose your instance with a caddy reverse proxy to - the hostname you’ve provided. Postgres will be initialized on that - same instance automatically. - </para> - </section> - <section xml:id="module-services-lemmy-usage"> - <title>Usage</title> - <para> - On first connection you will be asked to define an admin user. - </para> - </section> - <section xml:id="module-services-lemmy-missing"> - <title>Missing</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Exposing with nginx is not implemented yet. - </para> - </listitem> - <listitem> - <para> - This has been tested using a local database with a unix socket - connection. Using different database settings will likely - require modifications - </para> - </listitem> - </itemizedlist> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/matomo.nix b/nixos/modules/services/web-apps/matomo.nix index 98451065995..eadf8b62b97 100644 --- a/nixos/modules/services/web-apps/matomo.nix +++ b/nixos/modules/services/web-apps/matomo.nix @@ -325,7 +325,7 @@ in { }; meta = { - doc = ./matomo.xml; + doc = ./matomo.md; maintainers = with lib.maintainers; [ florianjacob ]; }; } diff --git a/nixos/modules/services/web-apps/matomo.xml b/nixos/modules/services/web-apps/matomo.xml deleted file mode 100644 index 30994cc9f1d..00000000000 --- a/nixos/modules/services/web-apps/matomo.xml +++ /dev/null @@ -1,107 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-matomo"> - <title>Matomo</title> - <para> - Matomo is a real-time web analytics application. This module - configures php-fpm as backend for Matomo, optionally configuring an - nginx vhost as well. - </para> - <para> - An automatic setup is not suported by Matomo, so you need to - configure Matomo itself in the browser-based Matomo setup. - </para> - <section xml:id="module-services-matomo-database-setup"> - <title>Database Setup</title> - <para> - You also need to configure a MariaDB or MySQL database and -user - for Matomo yourself, and enter those credentials in your browser. - You can use passwordless database authentication via the - UNIX_SOCKET authentication plugin with the following SQL commands: - </para> - <programlisting> -# For MariaDB -INSTALL PLUGIN unix_socket SONAME 'auth_socket'; -CREATE DATABASE matomo; -CREATE USER 'matomo'@'localhost' IDENTIFIED WITH unix_socket; -GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; - -# For MySQL -INSTALL PLUGIN auth_socket SONAME 'auth_socket.so'; -CREATE DATABASE matomo; -CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket; -GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost'; -</programlisting> - <para> - Then fill in <literal>matomo</literal> as database user and - database name, and leave the password field blank. This - authentication works by allowing only the - <literal>matomo</literal> unix user to authenticate as the - <literal>matomo</literal> database user (without needing a - password), but no other users. For more information on - passwordless login, see - <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/">https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/</link>. - </para> - <para> - Of course, you can use password based authentication as well, e.g. - when the database is not on the same host. - </para> - </section> - <section xml:id="module-services-matomo-archive-processing"> - <title>Archive Processing</title> - <para> - This module comes with the systemd service - <literal>matomo-archive-processing.service</literal> and a timer - that automatically triggers archive processing every hour. This - means that you can safely - <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour">disable - browser triggers for Matomo archiving</link> at - <literal>Administration > System > General Settings</literal>. - </para> - <para> - With automatic archive processing, you can now also enable to - <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs">delete - old visitor logs</link> at - <literal>Administration > System > Privacy</literal>, but - make sure that you run - <literal>systemctl start matomo-archive-processing.service</literal> - at least once without errors if you have already collected data - before, so that the reports get archived before the source data - gets deleted. - </para> - </section> - <section xml:id="module-services-matomo-backups"> - <title>Backup</title> - <para> - You only need to take backups of your MySQL database and the - <filename>/var/lib/matomo/config/config.ini.php</filename> file. - Use a user in the <literal>matomo</literal> group or root to - access the file. For more information, see - <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/">https://matomo.org/faq/how-to-install/faq_138/</link>. - </para> - </section> - <section xml:id="module-services-matomo-issues"> - <title>Issues</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Matomo will warn you that the JavaScript tracker is not - writable. This is because it’s located in the read-only nix - store. You can safely ignore this, unless you need a plugin - that needs JavaScript tracker access. - </para> - </listitem> - </itemizedlist> - </section> - <section xml:id="module-services-matomo-other-web-servers"> - <title>Using other Web Servers than nginx</title> - <para> - You can use other web servers by forwarding calls for - <filename>index.php</filename> and <filename>piwik.php</filename> - to the - <link linkend="opt-services.phpfpm.pools._name_.socket"><literal>services.phpfpm.pools.<name>.socket</literal></link> - fastcgi unix socket. You can use the nginx configuration in the - module code as a reference to what else should be configured. - </para> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/nextcloud.nix b/nixos/modules/services/web-apps/nextcloud.nix index 90801e99681..50c2d68c77e 100644 --- a/nixos/modules/services/web-apps/nextcloud.nix +++ b/nixos/modules/services/web-apps/nextcloud.nix @@ -1146,5 +1146,5 @@ in { } ]); - meta.doc = ./nextcloud.xml; + meta.doc = ./nextcloud.md; } diff --git a/nixos/modules/services/web-apps/nextcloud.xml b/nixos/modules/services/web-apps/nextcloud.xml deleted file mode 100644 index a5ac05723ef..00000000000 --- a/nixos/modules/services/web-apps/nextcloud.xml +++ /dev/null @@ -1,333 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-nextcloud"> - <title>Nextcloud</title> - <para> - <link xlink:href="https://nextcloud.com/">Nextcloud</link> is an - open-source, self-hostable cloud platform. The server setup can be - automated using - <link linkend="opt-services.nextcloud.enable">services.nextcloud</link>. - A desktop client is packaged at - <literal>pkgs.nextcloud-client</literal>. - </para> - <para> - The current default by NixOS is <literal>nextcloud25</literal> which - is also the latest major version available. - </para> - <section xml:id="module-services-nextcloud-basic-usage"> - <title>Basic usage</title> - <para> - Nextcloud is a PHP-based application which requires an HTTP server - (<link linkend="opt-services.nextcloud.enable"><literal>services.nextcloud</literal></link> - optionally supports - <link linkend="opt-services.nginx.enable"><literal>services.nginx</literal></link>) - and a database (it’s recommended to use - <link linkend="opt-services.postgresql.enable"><literal>services.postgresql</literal></link>). - </para> - <para> - A very basic configuration may look like this: - </para> - <programlisting> -{ pkgs, ... }: -{ - services.nextcloud = { - enable = true; - hostName = "nextcloud.tld"; - config = { - dbtype = "pgsql"; - dbuser = "nextcloud"; - dbhost = "/run/postgresql"; # nextcloud will add /.s.PGSQL.5432 by itself - dbname = "nextcloud"; - adminpassFile = "/path/to/admin-pass-file"; - adminuser = "root"; - }; - }; - - services.postgresql = { - enable = true; - ensureDatabases = [ "nextcloud" ]; - ensureUsers = [ - { name = "nextcloud"; - ensurePermissions."DATABASE nextcloud" = "ALL PRIVILEGES"; - } - ]; - }; - - # ensure that postgres is running *before* running the setup - systemd.services."nextcloud-setup" = { - requires = ["postgresql.service"]; - after = ["postgresql.service"]; - }; - - networking.firewall.allowedTCPPorts = [ 80 443 ]; -} -</programlisting> - <para> - The <literal>hostName</literal> option is used internally to - configure an HTTP server using - <link xlink:href="https://php-fpm.org/"><literal>PHP-FPM</literal></link> - and <literal>nginx</literal>. The <literal>config</literal> - attribute set is used by the imperative installer and all values - are written to an additional file to ensure that changes can be - applied by changing the module’s options. - </para> - <para> - In case the application serves multiple domains (those are checked - with - <link xlink:href="http://php.net/manual/en/reserved.variables.server.php"><literal>$_SERVER['HTTP_HOST']</literal></link>) - it’s needed to add them to - <link linkend="opt-services.nextcloud.config.extraTrustedDomains"><literal>services.nextcloud.config.extraTrustedDomains</literal></link>. - </para> - <para> - Auto updates for Nextcloud apps can be enabled using - <link linkend="opt-services.nextcloud.autoUpdateApps.enable"><literal>services.nextcloud.autoUpdateApps</literal></link>. - </para> - </section> - <section xml:id="module-services-nextcloud-pitfalls-during-upgrade"> - <title>Common problems</title> - <itemizedlist> - <listitem> - <para> - <emphasis role="strong">General notes.</emphasis> - Unfortunately Nextcloud appears to be very stateful when it - comes to managing its own configuration. The config file lives - in the home directory of the <literal>nextcloud</literal> user - (by default - <literal>/var/lib/nextcloud/config/config.php</literal>) and - is also used to track several states of the application (e.g., - whether installed or not). - </para> - <para> - All configuration parameters are also stored in - <filename>/var/lib/nextcloud/config/override.config.php</filename> - which is generated by the module and linked from the store to - ensure that all values from <filename>config.php</filename> - can be modified by the module. However - <filename>config.php</filename> manages the application’s - state and shouldn’t be touched manually because of that. - </para> - <warning> - <para> - Don’t delete <filename>config.php</filename>! This file - tracks the application’s state and a deletion can cause - unwanted side-effects! - </para> - </warning> - <warning> - <para> - Don’t rerun - <literal>nextcloud-occ maintenance:install</literal>! This - command tries to install the application and can cause - unwanted side-effects! - </para> - </warning> - </listitem> - <listitem> - <para> - <emphasis role="strong">Multiple version upgrades.</emphasis> - Nextcloud doesn’t allow to move more than one major-version - forward. E.g., if you’re on <literal>v16</literal>, you cannot - upgrade to <literal>v18</literal>, you need to upgrade to - <literal>v17</literal> first. This is ensured automatically as - long as the - <link linkend="opt-system.stateVersion">stateVersion</link> is - declared properly. In that case the oldest version available - (one major behind the one from the previous NixOS release) - will be selected by default and the module will generate a - warning that reminds the user to upgrade to latest Nextcloud - <emphasis>after</emphasis> that deploy. - </para> - </listitem> - <listitem> - <para> - <emphasis role="strong"><literal>Error: Command "upgrade" is not defined.</literal></emphasis> - This error usually occurs if the initial installation - (<command>nextcloud-occ maintenance:install</command>) has - failed. After that, the application is not installed, but the - upgrade is attempted to be executed. Further context can be - found in - <link xlink:href="https://github.com/NixOS/nixpkgs/issues/111175">NixOS/nixpkgs#111175</link>. - </para> - <para> - First of all, it makes sense to find out what went wrong by - looking at the logs of the installation via - <command>journalctl -u nextcloud-setup</command> and try to - fix the underlying issue. - </para> - <itemizedlist> - <listitem> - <para> - If this occurs on an <emphasis>existing</emphasis> setup, - this is most likely because the maintenance mode is - active. It can be deactivated by running - <command>nextcloud-occ maintenance:mode --off</command>. - It’s advisable though to check the logs first on why the - maintenance mode was activated. - </para> - </listitem> - <listitem> - <warning> - <para> - Only perform the following measures on <emphasis>freshly - installed instances!</emphasis> - </para> - </warning> - <para> - A re-run of the installer can be forced by - <emphasis>deleting</emphasis> - <filename>/var/lib/nextcloud/config/config.php</filename>. - This is the only time advisable because the fresh install - doesn’t have any state that can be lost. In case that - doesn’t help, an entire re-creation can be forced via - <command>rm -rf ~nextcloud/</command>. - </para> - </listitem> - </itemizedlist> - </listitem> - <listitem> - <para> - <emphasis role="strong">Server-side encryption.</emphasis> - Nextcloud supports - <link xlink:href="https://docs.nextcloud.com/server/latest/admin_manual/configuration_files/encryption_configuration.html">server-side - encryption (SSE)</link>. This is not an end-to-end encryption, - but can be used to encrypt files that will be persisted to - external storage such as S3. Please note that this won’t work - anymore when using OpenSSL 3 for PHP’s openssl extension - because this is implemented using the legacy cipher RC4. If - <xref linkend="opt-system.stateVersion" /> is - <emphasis>above</emphasis> <literal>22.05</literal>, this is - disabled by default. To turn it on again and for further - information please refer to - <xref linkend="opt-services.nextcloud.enableBrokenCiphersForSSE" />. - </para> - </listitem> - </itemizedlist> - </section> - <section xml:id="module-services-nextcloud-httpd"> - <title>Using an alternative webserver as reverse-proxy (e.g. - <literal>httpd</literal>)</title> - <para> - By default, <literal>nginx</literal> is used as reverse-proxy for - <literal>nextcloud</literal>. However, it’s possible to use e.g. - <literal>httpd</literal> by explicitly disabling - <literal>nginx</literal> using - <xref linkend="opt-services.nginx.enable" /> and fixing the - settings <literal>listen.owner</literal> & - <literal>listen.group</literal> in the - <link linkend="opt-services.phpfpm.pools">corresponding - <literal>phpfpm</literal> pool</link>. - </para> - <para> - An exemplary configuration may look like this: - </para> - <programlisting> -{ config, lib, pkgs, ... }: { - services.nginx.enable = false; - services.nextcloud = { - enable = true; - hostName = "localhost"; - - /* further, required options */ - }; - services.phpfpm.pools.nextcloud.settings = { - "listen.owner" = config.services.httpd.user; - "listen.group" = config.services.httpd.group; - }; - services.httpd = { - enable = true; - adminAddr = "webmaster@localhost"; - extraModules = [ "proxy_fcgi" ]; - virtualHosts."localhost" = { - documentRoot = config.services.nextcloud.package; - extraConfig = '' - <Directory "${config.services.nextcloud.package}"> - <FilesMatch "\.php$"> - <If "-f %{REQUEST_FILENAME}"> - SetHandler "proxy:unix:${config.services.phpfpm.pools.nextcloud.socket}|fcgi://localhost/" - </If> - </FilesMatch> - <IfModule mod_rewrite.c> - RewriteEngine On - RewriteBase / - RewriteRule ^index\.php$ - [L] - RewriteCond %{REQUEST_FILENAME} !-f - RewriteCond %{REQUEST_FILENAME} !-d - RewriteRule . /index.php [L] - </IfModule> - DirectoryIndex index.php - Require all granted - Options +FollowSymLinks - </Directory> - ''; - }; - }; -} -</programlisting> - </section> - <section xml:id="installing-apps-php-extensions-nextcloud"> - <title>Installing Apps and PHP extensions</title> - <para> - Nextcloud apps are installed statefully through the web interface. - Some apps may require extra PHP extensions to be installed. This - can be configured with the - <xref linkend="opt-services.nextcloud.phpExtraExtensions" /> - setting. - </para> - <para> - Alternatively, extra apps can also be declared with the - <xref linkend="opt-services.nextcloud.extraApps" /> setting. When - using this setting, apps can no longer be managed statefully - because this can lead to Nextcloud updating apps that are managed - by Nix. If you want automatic updates it is recommended that you - use web interface to install apps. - </para> - </section> - <section xml:id="module-services-nextcloud-maintainer-info"> - <title>Maintainer information</title> - <para> - As stated in the previous paragraph, we must provide a clean - upgrade-path for Nextcloud since it cannot move more than one - major version forward on a single upgrade. This chapter adds some - notes how Nextcloud updates should be rolled out in the future. - </para> - <para> - While minor and patch-level updates are no problem and can be done - directly in the package-expression (and should be backported to - supported stable branches after that), major-releases should be - added in a new attribute (e.g. Nextcloud - <literal>v19.0.0</literal> should be available in - <literal>nixpkgs</literal> as - <literal>pkgs.nextcloud19</literal>). To provide simple upgrade - paths it’s generally useful to backport those as well to stable - branches. As long as the package-default isn’t altered, this won’t - break existing setups. After that, the versioning-warning in the - <literal>nextcloud</literal>-module should be updated to make sure - that the - <link linkend="opt-services.nextcloud.package">package</link>-option - selects the latest version on fresh setups. - </para> - <para> - If major-releases will be abandoned by upstream, we should check - first if those are needed in NixOS for a safe upgrade-path before - removing those. In that case we should keep those packages, but - mark them as insecure in an expression like this (in - <literal><nixpkgs/pkgs/servers/nextcloud/default.nix></literal>): - </para> - <programlisting> -/* ... */ -{ - nextcloud17 = generic { - version = "17.0.x"; - sha256 = "0000000000000000000000000000000000000000000000000000"; - eol = true; - }; -} -</programlisting> - <para> - Ideally we should make sure that it’s possible to jump two NixOS - versions forward: i.e. the warnings and the logic in the module - should guard a user to upgrade from a Nextcloud on e.g. 19.09 to a - Nextcloud on 20.09. - </para> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/pict-rs.nix b/nixos/modules/services/web-apps/pict-rs.nix index ad07507ca37..0f13b2ae6db 100644 --- a/nixos/modules/services/web-apps/pict-rs.nix +++ b/nixos/modules/services/web-apps/pict-rs.nix @@ -5,7 +5,7 @@ let in { meta.maintainers = with maintainers; [ happysalada ]; - meta.doc = ./pict-rs.xml; + meta.doc = ./pict-rs.md; options.services.pict-rs = { enable = mkEnableOption (lib.mdDoc "pict-rs server"); diff --git a/nixos/modules/services/web-apps/pict-rs.xml b/nixos/modules/services/web-apps/pict-rs.xml deleted file mode 100644 index 3f5900c55f1..00000000000 --- a/nixos/modules/services/web-apps/pict-rs.xml +++ /dev/null @@ -1,185 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-pict-rs"> - <title>Pict-rs</title> - <para> - pict-rs is a a simple image hosting service. - </para> - <section xml:id="module-services-pict-rs-quickstart"> - <title>Quickstart</title> - <para> - the minimum to start pict-rs is - </para> - <programlisting language="nix"> -services.pict-rs.enable = true; -</programlisting> - <para> - this will start the http server on port 8080 by default. - </para> - </section> - <section xml:id="module-services-pict-rs-usage"> - <title>Usage</title> - <para> - pict-rs offers the following endpoints: - </para> - <itemizedlist> - <listitem> - <para> - <literal>POST /image</literal> for uploading an image. - Uploaded content must be valid multipart/form-data with an - image array located within the <literal>images[]</literal> key - </para> - <para> - This endpoint returns the following JSON structure on success - with a 201 Created status - </para> - <programlisting language="json"> -{ - "files": [ - { - "delete_token": "JFvFhqJA98", - "file": "lkWZDRvugm.jpg" - }, - { - "delete_token": "kAYy9nk2WK", - "file": "8qFS0QooAn.jpg" - }, - { - "delete_token": "OxRpM3sf0Y", - "file": "1hJaYfGE01.jpg" - } - ], - "msg": "ok" -} -</programlisting> - </listitem> - <listitem> - <para> - <literal>GET /image/download?url=...</literal> Download an - image from a remote server, returning the same JSON payload as - the <literal>POST</literal> endpoint - </para> - </listitem> - <listitem> - <para> - <literal>GET /image/original/{file}</literal> for getting a - full-resolution image. <literal>file</literal> here is the - <literal>file</literal> key from the <literal>/image</literal> - endpoint’s JSON - </para> - </listitem> - <listitem> - <para> - <literal>GET /image/details/original/{file}</literal> for - getting the details of a full-resolution image. The returned - JSON is structured like so: - </para> - <programlisting language="json"> -{ - "width": 800, - "height": 537, - "content_type": "image/webp", - "created_at": [ - 2020, - 345, - 67376, - 394363487 - ] -} -</programlisting> - </listitem> - <listitem> - <para> - <literal>GET /image/process.{ext}?src={file}&...</literal> - get a file with transformations applied. existing - transformations include - </para> - <itemizedlist spacing="compact"> - <listitem> - <para> - <literal>identity=true</literal>: apply no changes - </para> - </listitem> - <listitem> - <para> - <literal>blur={float}</literal>: apply a gaussian blur to - the file - </para> - </listitem> - <listitem> - <para> - <literal>thumbnail={int}</literal>: produce a thumbnail of - the image fitting inside an <literal>{int}</literal> by - <literal>{int}</literal> square using raw pixel sampling - </para> - </listitem> - <listitem> - <para> - <literal>resize={int}</literal>: produce a thumbnail of - the image fitting inside an <literal>{int}</literal> by - <literal>{int}</literal> square using a Lanczos2 filter. - This is slower than sampling but looks a bit better in - some cases - </para> - </listitem> - <listitem> - <para> - <literal>crop={int-w}x{int-h}</literal>: produce a cropped - version of the image with an <literal>{int-w}</literal> by - <literal>{int-h}</literal> aspect ratio. The resulting - crop will be centered on the image. Either the width or - height of the image will remain full-size, depending on - the image’s aspect ratio and the requested aspect ratio. - For example, a 1600x900 image cropped with a 1x1 aspect - ratio will become 900x900. A 1600x1100 image cropped with - a 16x9 aspect ratio will become 1600x900. - </para> - </listitem> - </itemizedlist> - <para> - Supported <literal>ext</literal> file extensions include - <literal>png</literal>, <literal>jpg</literal>, and - <literal>webp</literal> - </para> - <para> - An example of usage could be - </para> - <programlisting> -GET /image/process.jpg?src=asdf.png&thumbnail=256&blur=3.0 -</programlisting> - <para> - which would create a 256x256px JPEG thumbnail and blur it - </para> - </listitem> - <listitem> - <para> - <literal>GET /image/details/process.{ext}?src={file}&...</literal> - for getting the details of a processed image. The returned - JSON is the same format as listed for the full-resolution - details endpoint. - </para> - </listitem> - <listitem> - <para> - <literal>DELETE /image/delete/{delete_token}/{file}</literal> - or <literal>GET /image/delete/{delete_token}/{file}</literal> - to delete a file, where <literal>delete_token</literal> and - <literal>file</literal> are from the <literal>/image</literal> - endpoint’s JSON - </para> - </listitem> - </itemizedlist> - </section> - <section xml:id="module-services-pict-rs-missing"> - <title>Missing</title> - <itemizedlist spacing="compact"> - <listitem> - <para> - Configuring the secure-api-key is not included yet. The - envisioned basic use case is consumption on localhost by other - services without exposing the service to the internet. - </para> - </listitem> - </itemizedlist> - </section> -</chapter> diff --git a/nixos/modules/services/web-apps/plausible.nix b/nixos/modules/services/web-apps/plausible.nix index e5dc1b10360..f64254d6252 100644 --- a/nixos/modules/services/web-apps/plausible.nix +++ b/nixos/modules/services/web-apps/plausible.nix @@ -292,5 +292,5 @@ in { }; meta.maintainers = with maintainers; [ ma27 ]; - meta.doc = ./plausible.xml; + meta.doc = ./plausible.md; } diff --git a/nixos/modules/services/web-apps/plausible.xml b/nixos/modules/services/web-apps/plausible.xml deleted file mode 100644 index 39ff004ffd9..00000000000 --- a/nixos/modules/services/web-apps/plausible.xml +++ /dev/null @@ -1,45 +0,0 @@ -<!-- Do not edit this file directly, edit its companion .md instead - and regenerate this file using nixos/doc/manual/md-to-db.sh --> -<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-plausible"> - <title>Plausible</title> - <para> - <link xlink:href="https://plausible.io/">Plausible</link> is a - privacy-friendly alternative to Google analytics. - </para> - <section xml:id="module-services-plausible-basic-usage"> - <title>Basic Usage</title> - <para> - At first, a secret key is needed to be generated. This can be done - with e.g. - </para> - <programlisting> -$ openssl rand -base64 64 -</programlisting> - <para> - After that, <literal>plausible</literal> can be deployed like - this: - </para> - <programlisting> -{ - services.plausible = { - enable = true; - adminUser = { - # activate is used to skip the email verification of the admin-user that's - # automatically created by plausible. This is only supported if - # postgresql is configured by the module. This is done by default, but - # can be turned off with services.plausible.database.postgres.setup. - activate = true; - email = "admin@localhost"; - passwordFile = "/run/secrets/plausible-admin-pwd"; - }; - server = { - baseUrl = "http://analytics.example.org"; - # secretKeybaseFile is a path to the file which contains the secret generated - # with openssl as described above. - secretKeybaseFile = "/run/secrets/plausible-secret-key-base"; - }; - }; -} -</programlisting> - </section> -</chapter> |