movefasta/nixpkgs
0
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2025-07-12 05:16:25 +03:00
Code Activity

Merge branch 'staging-next' into staging

Browse source
This commit is contained in:
Jan Tojnar 2019-09-18 22:40:42 +02:00
commit 0902f08e0d
No known key found for this signature in database
GPG key ID: 7FAB2A15F7A607A4
172 changed files with 3044 additions and 10056 deletions
Download patch file Download diff file Expand all files Collapse all files

197
nixos/modules/services/databases/foundationdb.xml
View file

@ -5,12 +5,10 @@
xml:id="module-services-foundationdb">
<title>FoundationDB</title>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/databases/foundationdb.nix</filename>
<emphasis>Source:</emphasis> <filename>modules/services/databases/foundationdb.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://apple.github.io/foundationdb/"/>
<emphasis>Upstream documentation:</emphasis> <link xlink:href="https://apple.github.io/foundationdb/"/>
</para>
<para>
<emphasis>Maintainer:</emphasis> Austin Seipp
@ -19,15 +17,13 @@
<emphasis>Available version(s):</emphasis> 5.1.x, 5.2.x, 6.0.x
</para>
<para>
FoundationDB (or "FDB") is an open source, distributed, transactional
key-value store.
FoundationDB (or "FDB") is an open source, distributed, transactional key-value store.
</para>
<section xml:id="module-services-foundationdb-configuring">
<title>Configuring and basic setup</title>
<para>
To enable FoundationDB, add the following to your
<filename>configuration.nix</filename>:
To enable FoundationDB, add the following to your <filename>configuration.nix</filename>:
<programlisting>
services.foundationdb.enable = true;
services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x
@ -35,18 +31,11 @@ services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x
</para>
<para>
The <option>services.foundationdb.package</option> option is required, and
must always be specified. Due to the fact FoundationDB network protocols and
on-disk storage formats may change between (major) versions, and upgrades
must be explicitly handled by the user, you must always manually specify
this yourself so that the NixOS module will use the proper version. Note
that minor, bugfix releases are always compatible.
The <option>services.foundationdb.package</option> option is required, and must always be specified. Due to the fact FoundationDB network protocols and on-disk storage formats may change between (major) versions, and upgrades must be explicitly handled by the user, you must always manually specify this yourself so that the NixOS module will use the proper version. Note that minor, bugfix releases are always compatible.
</para>
<para>
After running <command>nixos-rebuild</command>, you can verify whether
FoundationDB is running by executing <command>fdbcli</command> (which is
added to <option>environment.systemPackages</option>):
After running <command>nixos-rebuild</command>, you can verify whether FoundationDB is running by executing <command>fdbcli</command> (which is added to <option>environment.systemPackages</option>):
<screen>
<prompt>$ </prompt>sudo -u foundationdb fdbcli
Using cluster file `/etc/foundationdb/fdb.cluster'.
@ -77,11 +66,7 @@ Cluster:
</para>
<para>
You can also write programs using the available client libraries. For
example, the following Python program can be run in order to grab the
cluster status, as a quick example. (This example uses
<command>nix-shell</command> shebang support to automatically supply the
necessary Python modules).
You can also write programs using the available client libraries. For example, the following Python program can be run in order to grab the cluster status, as a quick example. (This example uses <command>nix-shell</command> shebang support to automatically supply the necessary Python modules).
<screen>
<prompt>a@link> </prompt>cat fdb-status.py
#! /usr/bin/env nix-shell
@ -111,91 +96,56 @@ FoundationDB available: True
</para>
<para>
FoundationDB is run under the <command>foundationdb</command> user and group
by default, but this may be changed in the NixOS configuration. The systemd
unit <command>foundationdb.service</command> controls the
<command>fdbmonitor</command> process.
FoundationDB is run under the <command>foundationdb</command> user and group by default, but this may be changed in the NixOS configuration. The systemd unit <command>foundationdb.service</command> controls the <command>fdbmonitor</command> process.
</para>
<para>
By default, the NixOS module for FoundationDB creates a single SSD-storage
based database for development and basic usage. This storage engine is
designed for SSDs and will perform poorly on HDDs; however it can handle far
more data than the alternative "memory" engine and is a better default
choice for most deployments. (Note that you can change the storage backend
on-the-fly for a given FoundationDB cluster using
<command>fdbcli</command>.)
By default, the NixOS module for FoundationDB creates a single SSD-storage based database for development and basic usage. This storage engine is designed for SSDs and will perform poorly on HDDs; however it can handle far more data than the alternative "memory" engine and is a better default choice for most deployments. (Note that you can change the storage backend on-the-fly for a given FoundationDB cluster using <command>fdbcli</command>.)
</para>
<para>
Furthermore, only 1 server process and 1 backup agent are started in the
default configuration. See below for more on scaling to increase this.
Furthermore, only 1 server process and 1 backup agent are started in the default configuration. See below for more on scaling to increase this.
</para>
<para>
FoundationDB stores all data for all server processes under
<filename>/var/lib/foundationdb</filename>. You can override this using
<option>services.foundationdb.dataDir</option>, e.g.
FoundationDB stores all data for all server processes under <filename>/var/lib/foundationdb</filename>. You can override this using <option>services.foundationdb.dataDir</option>, e.g.
<programlisting>
services.foundationdb.dataDir = "/data/fdb";
</programlisting>
</para>
<para>
Similarly, logs are stored under <filename>/var/log/foundationdb</filename>
by default, and there is a corresponding
<option>services.foundationdb.logDir</option> as well.
Similarly, logs are stored under <filename>/var/log/foundationdb</filename> by default, and there is a corresponding <option>services.foundationdb.logDir</option> as well.
</para>
</section>
<section xml:id="module-services-foundationdb-scaling">
<title>Scaling processes and backup agents</title>
<para>
Scaling the number of server processes is quite easy; simply specify
<option>services.foundationdb.serverProcesses</option> to be the number of
FoundationDB worker processes that should be started on the machine.
Scaling the number of server processes is quite easy; simply specify <option>services.foundationdb.serverProcesses</option> to be the number of FoundationDB worker processes that should be started on the machine.
</para>
<para>
FoundationDB worker processes typically require 4GB of RAM per-process at
minimum for good performance, so this option is set to 1 by default since
the maximum amount of RAM is unknown. You're advised to abide by this
restriction, so pick a number of processes so that each has 4GB or more.
FoundationDB worker processes typically require 4GB of RAM per-process at minimum for good performance, so this option is set to 1 by default since the maximum amount of RAM is unknown. You're advised to abide by this restriction, so pick a number of processes so that each has 4GB or more.
</para>
<para>
A similar option exists in order to scale backup agent processes,
<option>services.foundationdb.backupProcesses</option>. Backup agents are
not as performance/RAM sensitive, so feel free to experiment with the number
of available backup processes.
A similar option exists in order to scale backup agent processes, <option>services.foundationdb.backupProcesses</option>. Backup agents are not as performance/RAM sensitive, so feel free to experiment with the number of available backup processes.
</para>
</section>
<section xml:id="module-services-foundationdb-clustering">
<title>Clustering</title>
<para>
FoundationDB on NixOS works similarly to other Linux systems, so this
section will be brief. Please refer to the full FoundationDB documentation
for more on clustering.
FoundationDB on NixOS works similarly to other Linux systems, so this section will be brief. Please refer to the full FoundationDB documentation for more on clustering.
</para>
<para>
FoundationDB organizes clusters using a set of
<emphasis>coordinators</emphasis>, which are just specially-designated
worker processes. By default, every installation of FoundationDB on NixOS
will start as its own individual cluster, with a single coordinator: the
first worker process on <command>localhost</command>.
FoundationDB organizes clusters using a set of <emphasis>coordinators</emphasis>, which are just specially-designated worker processes. By default, every installation of FoundationDB on NixOS will start as its own individual cluster, with a single coordinator: the first worker process on <command>localhost</command>.
</para>
<para>
Coordinators are specified globally using the
<command>/etc/foundationdb/fdb.cluster</command> file, which all servers and
client applications will use to find and join coordinators. Note that this
file <emphasis>can not</emphasis> be managed by NixOS so easily:
FoundationDB is designed so that it will rewrite the file at runtime for all
clients and nodes when cluster coordinators change, with clients
transparently handling this without intervention. It is fundamentally a
mutable file, and you should not try to manage it in any way in NixOS.
Coordinators are specified globally using the <command>/etc/foundationdb/fdb.cluster</command> file, which all servers and client applications will use to find and join coordinators. Note that this file <emphasis>can not</emphasis> be managed by NixOS so easily: FoundationDB is designed so that it will rewrite the file at runtime for all clients and nodes when cluster coordinators change, with clients transparently handling this without intervention. It is fundamentally a mutable file, and you should not try to manage it in any way in NixOS.
</para>
<para>
@ -216,9 +166,7 @@ services.foundationdb.dataDir = "/data/fdb";
</itemizedlist>
<para>
A node must already be a member of the cluster in order to properly be
promoted to a coordinator, so you must always add it first if you wish to
promote it.
A node must already be a member of the cluster in order to properly be promoted to a coordinator, so you must always add it first if you wish to promote it.
</para>
<para>
@ -233,37 +181,26 @@ services.foundationdb.dataDir = "/data/fdb";
</listitem>
<listitem>
<para>
Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this
server to all the other servers. Restart FoundationDB on all of these
other servers, so they join the cluster.
Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this server to all the other servers. Restart FoundationDB on all of these other servers, so they join the cluster.
</para>
</listitem>
<listitem>
<para>
All of these servers are now connected and working together in the
cluster, under the chosen coordinator.
All of these servers are now connected and working together in the cluster, under the chosen coordinator.
</para>
</listitem>
</itemizedlist>
<para>
At this point, you can add as many nodes as you want by just repeating the
above steps. By default there will still be a single coordinator: you can
use <command>fdbcli</command> to change this and add new coordinators.
At this point, you can add as many nodes as you want by just repeating the above steps. By default there will still be a single coordinator: you can use <command>fdbcli</command> to change this and add new coordinators.
</para>
<para>
As a convenience, FoundationDB can automatically assign coordinators based
on the redundancy mode you wish to achieve for the cluster. Once all the
nodes have been joined, simply set the replication policy, and then issue
the <command>coordinators auto</command> command
As a convenience, FoundationDB can automatically assign coordinators based on the redundancy mode you wish to achieve for the cluster. Once all the nodes have been joined, simply set the replication policy, and then issue the <command>coordinators auto</command> command
</para>
<para>
For example, assuming we have 3 nodes available, we can enable double
redundancy mode, then auto-select coordinators. For double redundancy, 3
coordinators is ideal: therefore FoundationDB will make
<emphasis>every</emphasis> node a coordinator automatically:
For example, assuming we have 3 nodes available, we can enable double redundancy mode, then auto-select coordinators. For double redundancy, 3 coordinators is ideal: therefore FoundationDB will make <emphasis>every</emphasis> node a coordinator automatically:
</para>
<screen>
@ -272,58 +209,33 @@ services.foundationdb.dataDir = "/data/fdb";
</screen>
<para>
This will transparently update all the servers within seconds, and
appropriately rewrite the <command>fdb.cluster</command> file, as well as
informing all client processes to do the same.
This will transparently update all the servers within seconds, and appropriately rewrite the <command>fdb.cluster</command> file, as well as informing all client processes to do the same.
</para>
</section>
<section xml:id="module-services-foundationdb-connectivity">
<title>Client connectivity</title>
<para>
By default, all clients must use the current <command>fdb.cluster</command>
file to access a given FoundationDB cluster. This file is located by default
in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the
FoundationDB service enabled, so you may copy the active one from your
cluster to a new node in order to connect, if it is not part of the cluster.
By default, all clients must use the current <command>fdb.cluster</command> file to access a given FoundationDB cluster. This file is located by default in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the FoundationDB service enabled, so you may copy the active one from your cluster to a new node in order to connect, if it is not part of the cluster.
</para>
</section>
<section xml:id="module-services-foundationdb-authorization">
<title>Client authorization and TLS</title>
<para>
By default, any user who can connect to a FoundationDB process with the
correct cluster configuration can access anything. FoundationDB uses a
pluggable design to transport security, and out of the box it supports a
LibreSSL-based plugin for TLS support. This plugin not only does in-flight
encryption, but also performs client authorization based on the given
endpoint's certificate chain. For example, a FoundationDB server may be
configured to only accept client connections over TLS, where the client TLS
certificate is from organization <emphasis>Acme Co</emphasis> in the
<emphasis>Research and Development</emphasis> unit.
By default, any user who can connect to a FoundationDB process with the correct cluster configuration can access anything. FoundationDB uses a pluggable design to transport security, and out of the box it supports a LibreSSL-based plugin for TLS support. This plugin not only does in-flight encryption, but also performs client authorization based on the given endpoint's certificate chain. For example, a FoundationDB server may be configured to only accept client connections over TLS, where the client TLS certificate is from organization <emphasis>Acme Co</emphasis> in the <emphasis>Research and Development</emphasis> unit.
</para>
<para>
Configuring TLS with FoundationDB is done using the
<option>services.foundationdb.tls</option> options in order to control the
peer verification string, as well as the certificate and its private key.
Configuring TLS with FoundationDB is done using the <option>services.foundationdb.tls</option> options in order to control the peer verification string, as well as the certificate and its private key.
</para>
<para>
Note that the certificate and its private key must be accessible to the
FoundationDB user account that the server runs under. These files are also
NOT managed by NixOS, as putting them into the store may reveal private
information.
Note that the certificate and its private key must be accessible to the FoundationDB user account that the server runs under. These files are also NOT managed by NixOS, as putting them into the store may reveal private information.
</para>
<para>
After you have a key and certificate file in place, it is not enough to
simply set the NixOS module options -- you must also configure the
<command>fdb.cluster</command> file to specify that a given set of
coordinators use TLS. This is as simple as adding the suffix
<command>:tls</command> to your cluster coordinator configuration, after the
port number. For example, assuming you have a coordinator on localhost with
the default configuration, simply specifying:
After you have a key and certificate file in place, it is not enough to simply set the NixOS module options -- you must also configure the <command>fdb.cluster</command> file to specify that a given set of coordinators use TLS. This is as simple as adding the suffix <command>:tls</command> to your cluster coordinator configuration, after the port number. For example, assuming you have a coordinator on localhost with the default configuration, simply specifying:
</para>
<programlisting>
@ -338,36 +250,19 @@ XXXXXX:XXXXXX@127.0.0.1:4500:tls
<title>Backups and Disaster Recovery</title>
<para>
The usual rules for doing FoundationDB backups apply on NixOS as written in
the FoundationDB manual. However, one important difference is the security
profile for NixOS: by default, the <command>foundationdb</command> systemd
unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to
the system, except for the log directory, data directory, and the
<command>/etc/foundationdb/</command> directory. This is enforced by default
and cannot be disabled.
The usual rules for doing FoundationDB backups apply on NixOS as written in the FoundationDB manual. However, one important difference is the security profile for NixOS: by default, the <command>foundationdb</command> systemd unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to the system, except for the log directory, data directory, and the <command>/etc/foundationdb/</command> directory. This is enforced by default and cannot be disabled.
</para>
<para>
However, a side effect of this is that the <command>fdbbackup</command>
command doesn't work properly for local filesystem backups: FoundationDB
uses a server process alongside the database processes to perform backups
and copy the backups to the filesystem. As a result, this process is put
under the restricted namespaces above: the backup process can only write to
a limited number of paths.
However, a side effect of this is that the <command>fdbbackup</command> command doesn't work properly for local filesystem backups: FoundationDB uses a server process alongside the database processes to perform backups and copy the backups to the filesystem. As a result, this process is put under the restricted namespaces above: the backup process can only write to a limited number of paths.
</para>
<para>
In order to allow flexible backup locations on local disks, the FoundationDB
NixOS module supports a
<option>services.foundationdb.extraReadWritePaths</option> option. This
option takes a list of paths, and adds them to the systemd unit, allowing
the processes inside the service to write (and read) the specified
directories.
In order to allow flexible backup locations on local disks, the FoundationDB NixOS module supports a <option>services.foundationdb.extraReadWritePaths</option> option. This option takes a list of paths, and adds them to the systemd unit, allowing the processes inside the service to write (and read) the specified directories.
</para>
<para>
For example, to create backups in <command>/opt/fdb-backups</command>, first
set up the paths in the module options:
For example, to create backups in <command>/opt/fdb-backups</command>, first set up the paths in the module options:
</para>
<programlisting>
@ -375,11 +270,7 @@ services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];
</programlisting>
<para>
Restart the FoundationDB service, and it will now be able to write to this
directory (even if it does not yet exist.) Note: this path
<emphasis>must</emphasis> exist before restarting the unit. Otherwise,
systemd will not include it in the private FoundationDB namespace (and it
will not add it dynamically at runtime).
Restart the FoundationDB service, and it will now be able to write to this directory (even if it does not yet exist.) Note: this path <emphasis>must</emphasis> exist before restarting the unit. Otherwise, systemd will not include it in the private FoundationDB namespace (and it will not add it dynamically at runtime).
</para>
<para>
@ -395,17 +286,13 @@ services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];
<title>Known limitations</title>
<para>
The FoundationDB setup for NixOS should currently be considered beta.
FoundationDB is not new software, but the NixOS compilation and integration
has only undergone fairly basic testing of all the available functionality.
The FoundationDB setup for NixOS should currently be considered beta. FoundationDB is not new software, but the NixOS compilation and integration has only undergone fairly basic testing of all the available functionality.
</para>
<itemizedlist>
<listitem>
<para>
There is no way to specify individual parameters for individual
<command>fdbserver</command> processes. Currently, all server processes
inherit all the global <command>fdbmonitor</command> settings.
There is no way to specify individual parameters for individual <command>fdbserver</command> processes. Currently, all server processes inherit all the global <command>fdbmonitor</command> settings.
</para>
</listitem>
<listitem>
@ -424,20 +311,14 @@ services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];
<title>Options</title>
<para>
NixOS's FoundationDB module allows you to configure all of the most relevant
configuration options for <command>fdbmonitor</command>, matching it quite
closely. A complete list of options for the FoundationDB module may be found
<link linkend="opt-services.foundationdb.enable">here</link>. You should
also read the FoundationDB documentation as well.
NixOS's FoundationDB module allows you to configure all of the most relevant configuration options for <command>fdbmonitor</command>, matching it quite closely. A complete list of options for the FoundationDB module may be found <link linkend="opt-services.foundationdb.enable">here</link>. You should also read the FoundationDB documentation as well.
</para>
</section>
<section xml:id="module-services-foundationdb-full-docs">
<title>Full documentation</title>
<para>
FoundationDB is a complex piece of software, and requires careful
administration to properly use. Full documentation for administration can be
found here: <link xlink:href="https://apple.github.io/foundationdb/"/>.
FoundationDB is a complex piece of software, and requires careful administration to properly use. Full documentation for administration can be found here: <link xlink:href="https://apple.github.io/foundationdb/"/>.
</para>
</section>
</chapter>

39
nixos/modules/services/databases/postgresql.xml
View file

@ -7,12 +7,10 @@
<!-- FIXME: render nicely -->
<!-- FIXME: source can be added automatically -->
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/databases/postgresql.nix</filename>
<emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="http://www.postgresql.org/docs/"/>
<emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/>
</para>
<!-- FIXME: more stuff, like maintainer? -->
<para>
@ -23,18 +21,12 @@
<title>Configuring</title>
<para>
To enable PostgreSQL, add the following to your
<filename>configuration.nix</filename>:
To enable PostgreSQL, add the following to your <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.postgresql.enable"/> = true;
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
</programlisting>
Note that you are required to specify the desired version of PostgreSQL
(e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your
PostgreSQL version requires a database dump and reload (see below), NixOS
cannot provide a default value for
<xref linkend="opt-services.postgresql.package"/> such as the most recent
release of PostgreSQL.
Note that you are required to specify the desired version of PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for <xref linkend="opt-services.postgresql.package"/> such as the most recent release of PostgreSQL.
</para>
<!--
@ -51,9 +43,7 @@ Type "help" for help.
-->
<para>
By default, PostgreSQL stores its databases in
<filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using
<xref linkend="opt-services.postgresql.dataDir"/>, e.g.
By default, PostgreSQL stores its databases in <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using <xref linkend="opt-services.postgresql.dataDir"/>, e.g.
<programlisting>
<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";
</programlisting>
@ -70,18 +60,14 @@ Type "help" for help.
<title>Options</title>
<para>
A complete list of options for the PostgreSQL module may be found
<link linkend="opt-services.postgresql.enable">here</link>.
A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.
</para>
</section>
<section xml:id="module-services-postgres-plugins">
<title>Plugins</title>
<para>
Plugins collection for each PostgreSQL version can be accessed with
<literal>.pkgs</literal>. For example, for
<literal>pkgs.postgresql_11</literal> package, its plugin collection is
accessed by <literal>pkgs.postgresql_11.pkgs</literal>:
Plugins collection for each PostgreSQL version can be accessed with <literal>.pkgs</literal>. For example, for <literal>pkgs.postgresql_11</literal> package, its plugin collection is accessed by <literal>pkgs.postgresql_11.pkgs</literal>:
<screen>
<prompt>$ </prompt>nix repl '&lt;nixpkgs&gt;'
@ -98,8 +84,9 @@ postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
...
</screen>
</para>
<para>
To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
<programlisting>
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
<xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [
@ -108,10 +95,9 @@ postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
];
</programlisting>
</para>
<para>
You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using
function <literal>.withPackages</literal>. For example, creating a custom
PostgreSQL package in an overlay can look like:
You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function <literal>.withPackages</literal>. For example, creating a custom PostgreSQL package in an overlay can look like:
<programlisting>
self: super: {
postgresql_custom = self.postgresql_11.withPackages (ps: [
@ -121,8 +107,9 @@ self: super: {
}
</programlisting>
</para>
<para>
Here's a recipe on how to override a particular plugin through an overlay:
Here's a recipe on how to override a particular plugin through an overlay:
<programlisting>
self: super: {
postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {

25
nixos/modules/services/desktops/flatpak.xml
View file

@ -5,44 +5,33 @@
xml:id="module-services-flatpak">
<title>Flatpak</title>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/desktop/flatpak.nix</filename>
<emphasis>Source:</emphasis> <filename>modules/services/desktop/flatpak.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://github.com/flatpak/flatpak/wiki"/>
<emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/flatpak/flatpak/wiki"/>
</para>
<para>
Flatpak is a system for building, distributing, and running sandboxed desktop
applications on Linux.
Flatpak is a system for building, distributing, and running sandboxed desktop applications on Linux.
</para>
<para>
To enable Flatpak, add the following to your
<filename>configuration.nix</filename>:
To enable Flatpak, add the following to your <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.flatpak.enable"/> = true;
</programlisting>
</para>
<para>
For the sandboxed apps to work correctly, desktop integration portals need to
be installed. If you run GNOME, this will be handled automatically for you;
in other cases, you will need to add something like the following to your
<filename>configuration.nix</filename>:
For the sandboxed apps to work correctly, desktop integration portals need to be installed. If you run GNOME, this will be handled automatically for you; in other cases, you will need to add something like the following to your <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-xdg.portal.extraPortals"/> = [ pkgs.xdg-desktop-portal-gtk ];
</programlisting>
</para>
<para>
Then, you will need to add a repository, for example,
<link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>,
either using the following commands:
Then, you will need to add a repository, for example, <link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>, either using the following commands:
<screen>
<prompt>$ </prompt>flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
<prompt>$ </prompt>flatpak update
</screen>
or by opening the
<link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository
file</link> in GNOME Software.
or by opening the <link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository file</link> in GNOME Software.
</para>
<para>
Finally, you can search and install programs:

221
nixos/modules/services/editors/emacs.xml
View file

@ -12,41 +12,26 @@
Adam Hoese @adisbladis
-->
<para>
<link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an
extensible, customizable, self-documenting real-time display editor — and
more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
programming language with extensions to support text editing.
<link xlink:href="https://www.gnu.org/software/emacs/">Emacs</link> is an extensible, customizable, self-documenting real-time display editor — and more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp programming language with extensions to support text editing.
</para>
<para>
Emacs runs within a graphical desktop environment using the X Window System,
but works equally well on a text terminal. Under
<productname>macOS</productname>, a "Mac port" edition is available, which
uses Apple's native GUI frameworks.
Emacs runs within a graphical desktop environment using the X Window System, but works equally well on a text terminal. Under <productname>macOS</productname>, a "Mac port" edition is available, which uses Apple's native GUI frameworks.
</para>
<para>
<productname>Nixpkgs</productname> provides a superior environment for
running <application>Emacs</application>. It's simple to create custom builds
by overriding the default packages. Chaotic collections of Emacs Lisp code
and extensions can be brought under control using declarative package
management. <productname>NixOS</productname> even provides a
<command>systemd</command> user service for automatically starting the Emacs
daemon.
<productname>Nixpkgs</productname> provides a superior environment for running <application>Emacs</application>. It's simple to create custom builds by overriding the default packages. Chaotic collections of Emacs Lisp code and extensions can be brought under control using declarative package management. <productname>NixOS</productname> even provides a <command>systemd</command> user service for automatically starting the Emacs daemon.
</para>
<section xml:id="module-services-emacs-installing">
<title>Installing <application>Emacs</application></title>
<para>
Emacs can be installed in the normal way for Nix (see
<xref linkend="sec-package-management" />). In addition, a NixOS
<emphasis>service</emphasis> can be enabled.
Emacs can be installed in the normal way for Nix (see <xref linkend="sec-package-management" />). In addition, a NixOS <emphasis>service</emphasis> can be enabled.
</para>
<section xml:id="module-services-emacs-releases">
<title>The Different Releases of Emacs</title>
<para>
<productname>Nixpkgs</productname> defines several basic Emacs packages.
The following are attributes belonging to the <varname>pkgs</varname> set:
<productname>Nixpkgs</productname> defines several basic Emacs packages. The following are attributes belonging to the <varname>pkgs</varname> set:
<variablelist>
<varlistentry>
<term>
@ -57,10 +42,8 @@
</term>
<listitem>
<para>
The latest stable version of Emacs 25 using the
<link
xlink:href="http://www.gtk.org">GTK 2</link>
widget toolkit.
The latest stable version of Emacs 25 using the <link
xlink:href="http://www.gtk.org">GTK 2</link> widget toolkit.
</para>
</listitem>
</varlistentry>
@ -83,8 +66,7 @@
</term>
<listitem>
<para>
Emacs 25 with the "Mac port" patches, providing a more native look and
feel under macOS.
Emacs 25 with the "Mac port" patches, providing a more native look and feel under macOS.
</para>
</listitem>
</varlistentry>
@ -92,12 +74,7 @@
</para>
<para>
If those aren't suitable, then the following imitation Emacs editors are
also available in Nixpkgs:
<link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
<link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
<link xlink:href="http://yi-editor.github.io/">Yi</link>,
<link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>.
If those aren't suitable, then the following imitation Emacs editors are also available in Nixpkgs: <link xlink:href="https://www.gnu.org/software/zile/">Zile</link>, <link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>, <link xlink:href="http://yi-editor.github.io/">Yi</link>, <link xlink:href="https://joe-editor.sourceforge.io/">jmacs</link>.
</para>
</section>
@ -105,36 +82,20 @@
<title>Adding Packages to Emacs</title>
<para>
Emacs includes an entire ecosystem of functionality beyond text editing,
including a project planner, mail and news reader, debugger interface,
calendar, and more.
Emacs includes an entire ecosystem of functionality beyond text editing, including a project planner, mail and news reader, debugger interface, calendar, and more.
</para>
<para>
Most extensions are gotten with the Emacs packaging system
(<filename>package.el</filename>) from
<link
xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive
(<acronym>ELPA</acronym>)</link>,
<link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>,
<link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and
<link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is
regularly updated to mirror all these archives.
Most extensions are gotten with the Emacs packaging system (<filename>package.el</filename>) from <link
xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive (<acronym>ELPA</acronym>)</link>, <link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>, <link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is regularly updated to mirror all these archives.
</para>
<para>
Under NixOS, you can continue to use
<function>package-list-packages</function> and
<function>package-install</function> to install packages. You can also
declare the set of Emacs packages you need using the derivations from
Nixpkgs. The rest of this section discusses declarative installation of
Emacs packages through nixpkgs.
Under NixOS, you can continue to use <function>package-list-packages</function> and <function>package-install</function> to install packages. You can also declare the set of Emacs packages you need using the derivations from Nixpkgs. The rest of this section discusses declarative installation of Emacs packages through nixpkgs.
</para>
<para>
The first step to declare the list of packages you want in your Emacs
installation is to create a dedicated derivation. This can be done in a
dedicated <filename>emacs.nix</filename> file such as:
The first step to declare the list of packages you want in your Emacs installation is to create a dedicated derivation. This can be done in a dedicated <filename>emacs.nix</filename> file such as:
<example xml:id="ex-emacsNix">
<title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
<programlisting language="nix">
@ -176,36 +137,27 @@ in
<calloutlist>
<callout arearefs="ex-emacsNix-1">
<para>
The first non-comment line in this file (<literal>{ pkgs ? ...
}</literal>) indicates that the whole file represents a function.
The first non-comment line in this file (<literal>{ pkgs ? ... }</literal>) indicates that the whole file represents a function.
</para>
</callout>
<callout arearefs="ex-emacsNix-2">
<para>
The <varname>let</varname> expression below defines a
<varname>myEmacs</varname> binding pointing to the current stable
version of Emacs. This binding is here to separate the choice of the
Emacs binary from the specification of the required packages.
The <varname>let</varname> expression below defines a <varname>myEmacs</varname> binding pointing to the current stable version of Emacs. This binding is here to separate the choice of the Emacs binary from the specification of the required packages.
</para>
</callout>
<callout arearefs="ex-emacsNix-3">
<para>
This generates an <varname>emacsWithPackages</varname> function. It
takes a single argument: a function from a package set to a list of
packages (the packages that will be available in Emacs).
This generates an <varname>emacsWithPackages</varname> function. It takes a single argument: a function from a package set to a list of packages (the packages that will be available in Emacs).
</para>
</callout>
<callout arearefs="ex-emacsNix-4">
<para>
The rest of the file specifies the list of packages to install. In the
example, two packages (<varname>magit</varname> and
<varname>zerodark-theme</varname>) are taken from MELPA stable.
The rest of the file specifies the list of packages to install. In the example, two packages (<varname>magit</varname> and <varname>zerodark-theme</varname>) are taken from MELPA stable.
</para>
</callout>
<callout arearefs="ex-emacsNix-5">
<para>
Two packages (<varname>undo-tree</varname> and
<varname>zoom-frm</varname>) are taken from MELPA.
Two packages (<varname>undo-tree</varname> and <varname>zoom-frm</varname>) are taken from MELPA.
</para>
</callout>
<callout arearefs="ex-emacsNix-6">
@ -215,17 +167,14 @@ in
</callout>
<callout arearefs="ex-emacsNix-7">
<para>
<varname>notmuch</varname> is taken from a nixpkgs derivation which
contains an Emacs mode.
<varname>notmuch</varname> is taken from a nixpkgs derivation which contains an Emacs mode.
</para>
</callout>
</calloutlist>
</para>
<para>
The result of this configuration will be an <command>emacs</command>
command which launches Emacs with all of your chosen packages in the
<varname>load-path</varname>.
The result of this configuration will be an <command>emacs</command> command which launches Emacs with all of your chosen packages in the <varname>load-path</varname>.
</para>
<para>
@ -234,23 +183,17 @@ in
<prompt>$ </prompt>nix-build emacs.nix
<prompt>$ </prompt>./result/bin/emacs -q
</screen>
and then typing <literal>M-x package-initialize</literal>. Check that you
can use all the packages you want in this Emacs instance. For example, try
switching to the zerodark theme through <literal>M-x load-theme &lt;RET&gt;
zerodark &lt;RET&gt; y</literal>.
and then typing <literal>M-x package-initialize</literal>. Check that you can use all the packages you want in this Emacs instance. For example, try switching to the zerodark theme through <literal>M-x load-theme &lt;RET&gt; zerodark &lt;RET&gt; y</literal>.
</para>
<tip>
<para>
A few popular extensions worth checking out are: auctex, company,
edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
and yasnippet.
A few popular extensions worth checking out are: auctex, company, edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile, and yasnippet.
</para>
</tip>
<para>
The list of available packages in the various ELPA repositories can be seen
with the following commands:
The list of available packages in the various ELPA repositories can be seen with the following commands:
<example xml:id="module-services-emacs-querying-packages">
<title>Querying Emacs packages</title>
<programlisting><![CDATA[
@ -263,10 +206,7 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackages.orgPackages
</para>
<para>
If you are on NixOS, you can install this particular Emacs for all users by
adding it to the list of system packages (see
<xref linkend="sec-declarative-package-mgmt" />). Simply modify your file
<filename>configuration.nix</filename> to make it contain:
If you are on NixOS, you can install this particular Emacs for all users by adding it to the list of system packages (see <xref linkend="sec-declarative-package-mgmt" />). Simply modify your file <filename>configuration.nix</filename> to make it contain:
<example xml:id="module-services-emacs-configuration-nix">
<title>Custom Emacs in <filename>configuration.nix</filename></title>
<programlisting><![CDATA[
@ -281,9 +221,7 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackages.orgPackages
</para>
<para>
In this case, the next <command>nixos-rebuild switch</command> will take
care of adding your <command>emacs</command> to the <varname>PATH</varname>
environment variable (see <xref linkend="sec-changing-config" />).
In this case, the next <command>nixos-rebuild switch</command> will take care of adding your <command>emacs</command> to the <varname>PATH</varname> environment variable (see <xref linkend="sec-changing-config" />).
</para>
<!-- fixme: i think the following is better done with config.nix
@ -291,11 +229,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
-->
<para>
If you are not on NixOS or want to install this particular Emacs only for
yourself, you can do so by adding it to your
<filename>~/.config/nixpkgs/config.nix</filename> (see
<link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs
manual</link>):
If you are not on NixOS or want to install this particular Emacs only for yourself, you can do so by adding it to your <filename>~/.config/nixpkgs/config.nix</filename> (see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>):
<example xml:id="module-services-emacs-config-nix">
<title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>
<programlisting><![CDATA[
@ -309,9 +243,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
</para>
<para>
In this case, the next <literal>nix-env -f '&lt;nixpkgs&gt;' -iA
myemacs</literal> will take care of adding your emacs to the
<varname>PATH</varname> environment variable.
In this case, the next <literal>nix-env -f '&lt;nixpkgs&gt;' -iA myemacs</literal> will take care of adding your emacs to the <varname>PATH</varname> environment variable.
</para>
</section>
@ -319,12 +251,7 @@ https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
<title>Advanced Emacs Configuration</title>
<para>
If you want, you can tweak the Emacs package itself from your
<filename>emacs.nix</filename>. For example, if you want to have a
GTK 3-based Emacs instead of the default GTK 2-based binary and remove the
automatically generated <filename>emacs.desktop</filename> (useful is you
only use <command>emacsclient</command>), you can change your file
<filename>emacs.nix</filename> in this way:
If you want, you can tweak the Emacs package itself from your <filename>emacs.nix</filename>. For example, if you want to have a GTK 3-based Emacs instead of the default GTK 2-based binary and remove the automatically generated <filename>emacs.desktop</filename> (useful is you only use <command>emacsclient</command>), you can change your file <filename>emacs.nix</filename> in this way:
</para>
<example xml:id="ex-emacsGtk3Nix">
@ -348,8 +275,7 @@ in [...]
</example>
<para>
After building this file as shown in <xref linkend="ex-emacsNix" />, you
will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
After building this file as shown in <xref linkend="ex-emacsNix" />, you will get an GTK 3-based Emacs binary pre-loaded with your favorite packages.
</para>
</section>
</section>
@ -357,23 +283,18 @@ in [...]
<title>Running Emacs as a Service</title>
<para>
<productname>NixOS</productname> provides an optional
<command>systemd</command> service which launches
<link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">
Emacs daemon </link> with the user's login session.
<productname>NixOS</productname> provides an optional <command>systemd</command> service which launches <link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html"> Emacs daemon </link> with the user's login session.
</para>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/editors/emacs.nix</filename>
<emphasis>Source:</emphasis> <filename>modules/services/editors/emacs.nix</filename>
</para>
<section xml:id="module-services-emacs-enabling">
<title>Enabling the Service</title>
<para>
To install and enable the <command>systemd</command> user service for Emacs
daemon, add the following to your <filename>configuration.nix</filename>:
To install and enable the <command>systemd</command> user service for Emacs daemon, add the following to your <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.emacs.enable"/> = true;
<xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; };
@ -381,16 +302,11 @@ in [...]
</para>
<para>
The <varname>services.emacs.package</varname> option allows a custom
derivation to be used, for example, one created by
<function>emacsWithPackages</function>.
The <varname>services.emacs.package</varname> option allows a custom derivation to be used, for example, one created by <function>emacsWithPackages</function>.
</para>
<para>
Ensure that the Emacs server is enabled for your user's Emacs
configuration, either by customizing the <varname>server-mode</varname>
variable, or by adding <literal>(server-start)</literal> to
<filename>~/.emacs.d/init.el</filename>.
Ensure that the Emacs server is enabled for your user's Emacs configuration, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs.d/init.el</filename>.
</para>
<para>
@ -408,9 +324,7 @@ in [...]
<title>Starting the client</title>
<para>
Ensure that the emacs server is enabled, either by customizing the
<varname>server-mode</varname> variable, or by adding
<literal>(server-start)</literal> to <filename>~/.emacs</filename>.
Ensure that the emacs server is enabled, either by customizing the <varname>server-mode</varname> variable, or by adding <literal>(server-start)</literal> to <filename>~/.emacs</filename>.
</para>
<para>
@ -429,23 +343,15 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
<!--<title><command>emacsclient</command> as the Default Editor</title>-->
<para>
If <xref linkend="opt-services.emacs.defaultEditor"/> is
<literal>true</literal>, the <varname>EDITOR</varname> variable will be set
to a wrapper script which launches <command>emacsclient</command>.
If <xref linkend="opt-services.emacs.defaultEditor"/> is <literal>true</literal>, the <varname>EDITOR</varname> variable will be set to a wrapper script which launches <command>emacsclient</command>.
</para>
<para>
Any setting of <varname>EDITOR</varname> in the shell config files will
override <varname>services.emacs.defaultEditor</varname>. To make sure
<varname>EDITOR</varname> refers to the Emacs wrapper script, remove any
existing <varname>EDITOR</varname> assignment from
<filename>.profile</filename>, <filename>.bashrc</filename>,
<filename>.zshenv</filename> or any other shell config file.
Any setting of <varname>EDITOR</varname> in the shell config files will override <varname>services.emacs.defaultEditor</varname>. To make sure <varname>EDITOR</varname> refers to the Emacs wrapper script, remove any existing <varname>EDITOR</varname> assignment from <filename>.profile</filename>, <filename>.bashrc</filename>, <filename>.zshenv</filename> or any other shell config file.
</para>
<para>
If you have formed certain bad habits when editing files, these can be
corrected with a shell alias to the wrapper script:
If you have formed certain bad habits when editing files, these can be corrected with a shell alias to the wrapper script:
<programlisting>alias vi=$EDITOR</programlisting>
</para>
</section>
@ -454,10 +360,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
<title>Per-User Enabling of the Service</title>
<para>
In general, <command>systemd</command> user services are globally enabled
by symlinks in <filename>/etc/systemd/user</filename>. In the case where
Emacs daemon is not wanted for all users, it is possible to install the
service but not globally enable it:
In general, <command>systemd</command> user services are globally enabled by symlinks in <filename>/etc/systemd/user</filename>. In the case where Emacs daemon is not wanted for all users, it is possible to install the service but not globally enable it:
<programlisting>
<xref linkend="opt-services.emacs.enable"/> = false;
<xref linkend="opt-services.emacs.install"/> = true;
@ -465,11 +368,9 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
</para>
<para>
To enable the <command>systemd</command> user service for just the
currently logged in user, run:
To enable the <command>systemd</command> user service for just the currently logged in user, run:
<programlisting>systemctl --user enable emacs</programlisting>
This will add the symlink
<filename>~/.config/systemd/user/emacs.service</filename>.
This will add the symlink <filename>~/.config/systemd/user/emacs.service</filename>.
</para>
</section>
</section>
@ -477,8 +378,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
<title>Configuring Emacs</title>
<para>
The Emacs init file should be changed to load the extension packages at
startup:
The Emacs init file should be changed to load the extension packages at startup:
<example xml:id="module-services-emacs-package-initialisation">
<title>Package initialization in <filename>.emacs</filename></title>
<programlisting><![CDATA[
@ -494,10 +394,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
</para>
<para>
After the declarative emacs package configuration has been tested,
previously downloaded packages can be cleaned up by removing
<filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you
forgot a package).
After the declarative emacs package configuration has been tested, previously downloaded packages can be cleaned up by removing <filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you forgot a package).
</para>
<!--
@ -509,9 +406,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
<title>A Major Mode for Nix Expressions</title>
<para>
Of interest may be <varname>melpaPackages.nix-mode</varname>, which
provides syntax highlighting for the Nix language. This is particularly
convenient if you regularly edit Nix files.
Of interest may be <varname>melpaPackages.nix-mode</varname>, which provides syntax highlighting for the Nix language. This is particularly convenient if you regularly edit Nix files.
</para>
</section>
@ -519,9 +414,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
<title>Accessing man pages</title>
<para>
You can use <function>woman</function> to get completion of all available
man pages. For example, type <literal>M-x woman &lt;RET&gt; nixos-rebuild
&lt;RET&gt;.</literal>
You can use <function>woman</function> to get completion of all available man pages. For example, type <literal>M-x woman &lt;RET&gt; nixos-rebuild &lt;RET&gt;.</literal>
</para>
</section>
@ -529,29 +422,17 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
<title>Editing DocBook 5 XML Documents</title>
<para>
Emacs includes
<link
xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,
a major-mode for validating and editing XML documents. When editing DocBook
5.0 documents, such as <link linkend="book-nixos-manual">this one</link>,
nXML needs to be configured with the relevant schema, which is not
included.
Emacs includes <link
xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>, a major-mode for validating and editing XML documents. When editing DocBook 5.0 documents, such as <link linkend="book-nixos-manual">this one</link>, nXML needs to be configured with the relevant schema, which is not included.
</para>
<para>
To install the DocBook 5.0 schemas, either add
<varname>pkgs.docbook5</varname> to
<xref linkend="opt-environment.systemPackages"/>
(<link
linkend="sec-declarative-package-mgmt">NixOS</link>), or run
<literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal>
(<link linkend="sec-ad-hoc-packages">Nix</link>).
To install the DocBook 5.0 schemas, either add <varname>pkgs.docbook5</varname> to <xref linkend="opt-environment.systemPackages"/> (<link
linkend="sec-declarative-package-mgmt">NixOS</link>), or run <literal>nix-env -f '&lt;nixpkgs&gt;' -iA docbook5</literal> (<link linkend="sec-ad-hoc-packages">Nix</link>).
</para>
<para>
Then customize the variable <varname>rng-schema-locating-files</varname> to
include <filename>~/.emacs.d/schemas.xml</filename> and put the following
text into that file:
Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file:
<example xml:id="ex-emacs-docbook-xml">
<title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
<programlisting language="xml"><![CDATA[

10
nixos/modules/services/hardware/trezord.xml
View file

@ -5,16 +5,10 @@
xml:id="trezor">
<title>Trezor</title>
<para>
Trezor is an open-source cryptocurrency hardware wallet and security token
allowing secure storage of private keys.
Trezor is an open-source cryptocurrency hardware wallet and security token allowing secure storage of private keys.
</para>
<para>
It offers advanced features such U2F two-factor authorization, SSH login
through
<link xlink:href="https://wiki.trezor.io/Apps:SSH_agent">Trezor SSH agent</link>,
<link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a
<link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>.
For more information, guides and documentation, see <link xlink:href="https://wiki.trezor.io"/>.
It offers advanced features such U2F two-factor authorization, SSH login through <link xlink:href="https://wiki.trezor.io/Apps:SSH_agent">Trezor SSH agent</link>, <link xlink:href="https://wiki.trezor.io/GPG">GPG</link> and a <link xlink:href="https://wiki.trezor.io/Trezor_Password_Manager">password manager</link>. For more information, guides and documentation, see <link xlink:href="https://wiki.trezor.io"/>.
</para>
<para>
To enable Trezor support, add the following to your <filename>configuration.nix</filename>:

34
nixos/modules/services/misc/gitlab.xml
View file

@ -11,14 +11,11 @@
<title>Prerequisites</title>
<para>
The gitlab service exposes only an Unix socket at
<literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to
configure a webserver to proxy HTTP requests to the socket.
The gitlab service exposes only an Unix socket at <literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a webserver to proxy HTTP requests to the socket.
</para>
<para>
For instance, the following configuration could be used to use nginx as
frontend proxy:
For instance, the following configuration could be used to use nginx as frontend proxy:
<programlisting>
<link linkend="opt-services.nginx.enable">services.nginx</link> = {
<link linkend="opt-services.nginx.enable">enable</link> = true;
@ -39,14 +36,11 @@
<title>Configuring</title>
<para>
Gitlab depends on both PostgreSQL and Redis and will automatically enable
both services. In the case of PostgreSQL, a database and a role will be
created.
Gitlab depends on both PostgreSQL and Redis and will automatically enable both services. In the case of PostgreSQL, a database and a role will be created.
</para>
<para>
The default state dir is <literal>/var/gitlab/state</literal>. This is where
all data like the repositories and uploads will be stored.
The default state dir is <literal>/var/gitlab/state</literal>. This is where all data like the repositories and uploads will be stored.
</para>
<para>
@ -85,31 +79,19 @@ services.gitlab = {
</para>
<para>
If you're setting up a new Gitlab instance, generate new
secrets. You for instance use <literal>tr -dc A-Za-z0-9 &lt;
/dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal> to
generate a new db secret. Make sure the files can be read by, and
only by, the user specified by <link
linkend="opt-services.gitlab.user">services.gitlab.user</link>. Gitlab
encrypts sensitive data stored in the database. If you're restoring
an existing Gitlab instance, you must specify the secrets secret
from <literal>config/secrets.yml</literal> located in your Gitlab
state folder.
If you're setting up a new Gitlab instance, generate new secrets. You for instance use <literal>tr -dc A-Za-z0-9 &lt; /dev/urandom | head -c 128 &gt; /var/keys/gitlab/db</literal> to generate a new db secret. Make sure the files can be read by, and only by, the user specified by <link
linkend="opt-services.gitlab.user">services.gitlab.user</link>. Gitlab encrypts sensitive data stored in the database. If you're restoring an existing Gitlab instance, you must specify the secrets secret from <literal>config/secrets.yml</literal> located in your Gitlab state folder.
</para>
<para>
Refer to <xref linkend="ch-options" /> for all available configuration
options for the
<link linkend="opt-services.gitlab.enable">services.gitlab</link> module.
Refer to <xref linkend="ch-options" /> for all available configuration options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.
</para>
</section>
<section xml:id="module-services-gitlab-maintenance">
<title>Maintenance</title>
<para>
You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which
will be available on the system when gitlab is enabled. You will have to run
the command as the user that you configured to run gitlab with.
You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which will be available on the system when gitlab is enabled. You will have to run the command as the user that you configured to run gitlab with.
</para>
<para>

74
nixos/modules/services/misc/taskserver/doc.xml
View file

@ -4,87 +4,58 @@
xml:id="module-taskserver">
<title>Taskserver</title>
<para>
Taskserver is the server component of
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
open source todo list application.
Taskserver is the server component of <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and open source todo list application.
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://taskwarrior.org/docs/#taskd"/>
<emphasis>Upstream documentation:</emphasis> <link xlink:href="https://taskwarrior.org/docs/#taskd"/>
</para>
<section xml:id="module-services-taskserver-configuration">
<title>Configuration</title>
<para>
Taskserver does all of its authentication via TLS using client certificates,
so you either need to roll your own CA or purchase a certificate from a
known CA, which allows creation of client certificates. These certificates
are usually advertised as <quote>server certificates</quote>.
Taskserver does all of its authentication via TLS using client certificates, so you either need to roll your own CA or purchase a certificate from a known CA, which allows creation of client certificates. These certificates are usually advertised as <quote>server certificates</quote>.
</para>
<para>
So in order to make it easier to handle your own CA, there is a helper tool
called <command>nixos-taskserver</command> which manages the custom CA along
with Taskserver organisations, users and groups.
So in order to make it easier to handle your own CA, there is a helper tool called <command>nixos-taskserver</command> which manages the custom CA along with Taskserver organisations, users and groups.
</para>
<para>
While the client certificates in Taskserver only authenticate whether a user
is allowed to connect, every user has its own UUID which identifies it as an
entity.
While the client certificates in Taskserver only authenticate whether a user is allowed to connect, every user has its own UUID which identifies it as an entity.
</para>
<para>
With <command>nixos-taskserver</command> the client certificate is created
along with the UUID of the user, so it handles all of the credentials needed
in order to setup the Taskwarrior client to work with a Taskserver.
With <command>nixos-taskserver</command> the client certificate is created along with the UUID of the user, so it handles all of the credentials needed in order to setup the Taskwarrior client to work with a Taskserver.
</para>
</section>
<section xml:id="module-services-taskserver-nixos-taskserver-tool">
<title>The nixos-taskserver tool</title>
<para>
Because Taskserver by default only provides scripts to setup users
imperatively, the <command>nixos-taskserver</command> tool is used for
addition and deletion of organisations along with users and groups defined
by <xref linkend="opt-services.taskserver.organisations"/> and as well for
imperative set up.
Because Taskserver by default only provides scripts to setup users imperatively, the <command>nixos-taskserver</command> tool is used for addition and deletion of organisations along with users and groups defined by <xref linkend="opt-services.taskserver.organisations"/> and as well for imperative set up.
</para>
<para>
The tool is designed to not interfere if the command is used to manually set
up some organisations, users or groups.
The tool is designed to not interfere if the command is used to manually set up some organisations, users or groups.
</para>
<para>
For example if you add a new organisation using <command>nixos-taskserver
org add foo</command>, the organisation is not modified and deleted no
matter what you define in
<option>services.taskserver.organisations</option>, even if you're adding
the same organisation in that option.
For example if you add a new organisation using <command>nixos-taskserver org add foo</command>, the organisation is not modified and deleted no matter what you define in <option>services.taskserver.organisations</option>, even if you're adding the same organisation in that option.
</para>
<para>
The tool is modelled to imitate the official <command>taskd</command>
command, documentation for each subcommand can be shown by using the
<option>--help</option> switch.
The tool is modelled to imitate the official <command>taskd</command> command, documentation for each subcommand can be shown by using the <option>--help</option> switch.
</para>
</section>
<section xml:id="module-services-taskserver-declarative-ca-management">
<title>Declarative/automatic CA management</title>
<para>
Everything is done according to what you specify in the module options,
however in order to set up a Taskwarrior client for synchronisation with a
Taskserver instance, you have to transfer the keys and certificates to the
client machine.
Everything is done according to what you specify in the module options, however in order to set up a Taskwarrior client for synchronisation with a Taskserver instance, you have to transfer the keys and certificates to the client machine.
</para>
<para>
This is done using <command>nixos-taskserver user export $orgname
$username</command> which is printing a shell script fragment to stdout
which can either be used verbatim or adjusted to import the user on the
client machine.
This is done using <command>nixos-taskserver user export $orgname $username</command> which is printing a shell script fragment to stdout which can either be used verbatim or adjusted to import the user on the client machine.
</para>
<para>
@ -97,39 +68,30 @@
<link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];
}
</screen>
This creates an organisation called <literal>my-company</literal> with the
user <literal>alice</literal>.
This creates an organisation called <literal>my-company</literal> with the user <literal>alice</literal>.
</para>
<para>
Now in order to import the <literal>alice</literal> user to another machine
<literal>alicebox</literal>, all we need to do is something like this:
Now in order to import the <literal>alice</literal> user to another machine <literal>alicebox</literal>, all we need to do is something like this:
<screen>
<prompt>$ </prompt>ssh server nixos-taskserver user export my-company alice | sh
</screen>
Of course, if no SSH daemon is available on the server you can also copy
&amp; paste it directly into a shell.
Of course, if no SSH daemon is available on the server you can also copy &amp; paste it directly into a shell.
</para>
<para>
After this step the user should be set up and you can start synchronising
your tasks for the first time with <command>task sync init</command> on
<literal>alicebox</literal>.
After this step the user should be set up and you can start synchronising your tasks for the first time with <command>task sync init</command> on <literal>alicebox</literal>.
</para>
<para>
Subsequent synchronisation requests merely require the command <command>task
sync</command> after that stage.
Subsequent synchronisation requests merely require the command <command>task sync</command> after that stage.
</para>
</section>
<section xml:id="module-services-taskserver-manual-ca-management">
<title>Manual CA management</title>
<para>
If you set any options within
<link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
<command>nixos-taskserver</command> won't issue certificates, but you can
still use it for adding or removing user accounts.
If you set any options within <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*, <command>nixos-taskserver</command> won't issue certificates, but you can still use it for adding or removing user accounts.
</para>
</section>
</chapter>

21
nixos/modules/services/misc/weechat.xml
View file

@ -5,18 +5,13 @@
xml:id="module-services-weechat">
<title>WeeChat</title>
<para>
<link xlink:href="https://weechat.org/">WeeChat</link> is a fast and
extensible IRC client.
<link xlink:href="https://weechat.org/">WeeChat</link> is a fast and extensible IRC client.
</para>
<section xml:id="module-services-weechat-basic-usage">
<title>Basic Usage</title>
<para>
By default, the module creates a
<literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal>
unit which runs the chat client in a detached
<literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal>
session.
By default, the module creates a <literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal> unit which runs the chat client in a detached <literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal> session.
</para>
<para>
@ -31,19 +26,14 @@
</para>
<para>
The service is managed by a dedicated user named <literal>weechat</literal>
in the state directory <literal>/var/lib/weechat</literal>.
The service is managed by a dedicated user named <literal>weechat</literal> in the state directory <literal>/var/lib/weechat</literal>.
</para>
</section>
<section xml:id="module-services-weechat-reattach">
<title>Re-attaching to WeeChat</title>
<para>
WeeChat runs in a screen session owned by a dedicated user. To explicitly
allow your another user to attach to this session, the
<literal>screenrc</literal> needs to be tweaked by adding
<link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link>
support:
WeeChat runs in a screen session owned by a dedicated user. To explicitly allow your another user to attach to this session, the <literal>screenrc</literal> needs to be tweaked by adding <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link> support:
<programlisting>
{
<link linkend="opt-programs.screen.screenrc">programs.screen.screenrc</link> = ''
@ -59,8 +49,7 @@ screen -x weechat/weechat-screen
</para>
<para>
<emphasis>The session name can be changed using
<link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>
<emphasis>The session name can be changed using <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>
</para>
</section>
</chapter>

51
nixos/modules/services/monitoring/prometheus/exporters.xml
View file

@ -5,17 +5,13 @@
xml:id="module-services-prometheus-exporters">
<title>Prometheus exporters</title>
<para>
Prometheus exporters provide metrics for the
<link xlink:href="https://prometheus.io">prometheus monitoring system</link>.
Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.
</para>
<section xml:id="module-services-prometheus-exporters-configuration">
<title>Configuration</title>
<para>
One of the most common exporters is the
<link xlink:href="https://github.com/prometheus/node_exporter">node
exporter</link>, it provides hardware and OS metrics from the host it's
running on. The exporter could be configured as follows:
One of the most common exporters is the <link xlink:href="https://github.com/prometheus/node_exporter">node exporter</link>, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows:
<programlisting>
services.prometheus.exporters.node = {
enable = true;
@ -30,34 +26,20 @@
firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
};
</programlisting>
It should now serve all metrics from the collectors that are explicitly
enabled and the ones that are
<link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled
by default</link>, via http under <literal>/metrics</literal>. In this
example the firewall should just allow incoming connections to the
exporter's port on the bridge interface <literal>br0</literal> (this would
have to be configured seperately of course). For more information about
configuration see <literal>man configuration.nix</literal> or search through
the
<link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available
options</link>.
It should now serve all metrics from the collectors that are explicitly enabled and the ones that are <link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled by default</link>, via http under <literal>/metrics</literal>. In this example the firewall should just allow incoming connections to the exporter's port on the bridge interface <literal>br0</literal> (this would have to be configured seperately of course). For more information about configuration see <literal>man configuration.nix</literal> or search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>.
</para>
</section>
<section xml:id="module-services-prometheus-exporters-new-exporter">
<title>Adding a new exporter</title>
<para>
To add a new exporter, it has to be packaged first (see
<literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for
examples), then a module can be added. The postfix exporter is used in this
example:
To add a new exporter, it has to be packaged first (see <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for examples), then a module can be added. The postfix exporter is used in this example:
</para>
<itemizedlist>
<listitem>
<para>
Some default options for all exporters are provided by
<literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
Some default options for all exporters are provided by <literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
</para>
</listitem>
<listitem override='none'>
@ -106,11 +88,7 @@
</listitem>
<listitem>
<para>
As there is already a package available, the module can now be added. This
is accomplished by adding a new file to the
<literal>nixos/modules/services/monitoring/prometheus/exporters/</literal>
directory, which will be called postfix.nix and contains all exporter
specific options and configuration:
As there is already a package available, the module can now be added. This is accomplished by adding a new file to the <literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> directory, which will be called postfix.nix and contains all exporter specific options and configuration:
<programlisting>
# nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix
{ config, lib, pkgs, options }:
@ -177,21 +155,16 @@ in
</listitem>
<listitem>
<para>
This should already be enough for the postfix exporter. Additionally one
could now add assertions and conditional default values. This can be done
in the 'meta-module' that combines all exporter definitions and generates
the submodules:
<literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
This should already be enough for the postfix exporter. Additionally one could now add assertions and conditional default values. This can be done in the 'meta-module' that combines all exporter definitions and generates the submodules: <literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="module-services-prometheus-exporters-update-exporter-module">
<title>Updating an exporter module</title>
<para>
Should an exporter option change at some point, it is possible to add
information about the change to the exporter definition similar to
<literal>nixpkgs/nixos/modules/rename.nix</literal>:
<para>
Should an exporter option change at some point, it is possible to add information about the change to the exporter definition similar to <literal>nixpkgs/nixos/modules/rename.nix</literal>:
<programlisting>
{ config, lib, pkgs, options }:
@ -222,6 +195,6 @@ in
];
}
</programlisting>
</para>
</section>
</para>
</section>
</chapter>

14
nixos/modules/services/networking/dnscrypt-proxy.xml
View file

@ -5,11 +5,7 @@
xml:id="sec-dnscrypt-proxy">
<title>DNSCrypt client proxy</title>
<para>
The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream
resolver. The traffic between the client and the upstream resolver is
encrypted and authenticated, mitigating the risk of MITM attacks, DNS
poisoning attacks, and third-party snooping (assuming the upstream is
trustworthy).
The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream resolver. The traffic between the client and the upstream resolver is encrypted and authenticated, mitigating the risk of MITM attacks, DNS poisoning attacks, and third-party snooping (assuming the upstream is trustworthy).
</para>
<sect1 xml:id="sec-dnscrypt-proxy-configuration">
<title>Basic configuration</title>
@ -22,18 +18,14 @@
</para>
<para>
Enabling the client proxy does not alter the system nameserver; to relay
local queries, prepend <literal>127.0.0.1</literal> to
<option>networking.nameservers</option>.
Enabling the client proxy does not alter the system nameserver; to relay local queries, prepend <literal>127.0.0.1</literal> to <option>networking.nameservers</option>.
</para>
</sect1>
<sect1 xml:id="sec-dnscrypt-proxy-forwarder">
<title>As a forwarder for another DNS client</title>
<para>
To run the DNSCrypt proxy client as a forwarder for another DNS client,
change the default proxy listening port to a non-standard value and point
the other client to it:
To run the DNSCrypt proxy client as a forwarder for another DNS client, change the default proxy listening port to a non-standard value and point the other client to it:
<programlisting>
<xref linkend="opt-services.dnscrypt-proxy.localPort"/> = 43;
</programlisting>

56
nixos/modules/services/web-apps/matomo-doc.xml
View file

@ -5,21 +5,16 @@
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.
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.
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:
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:
<programlisting>
# For MariaDB
INSTALL PLUGIN unix_socket SONAME 'auth_socket';
@ -33,51 +28,29 @@ CREATE DATABASE matomo;
CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket;
GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';
</programlisting>
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/" />.
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/" />.
</para>
<para>
Of course, you can use password based authentication as well, e.g. when the
database is not on the same host.
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>.
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.
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/" />.
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/" />.
</para>
</section>
<section xml:id="module-services-matomo-issues">
@ -86,15 +59,12 @@ GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';
<itemizedlist>
<listitem>
<para>
Matomo's file integrity check will warn you. This is due to the patches
necessary for NixOS, you can safely ignore this.
Matomo's file integrity check will warn you. This is due to the patches necessary for NixOS, you can safely ignore this.
</para>
</listitem>
<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.
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>
@ -103,11 +73,7 @@ GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';
<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
<literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use
the nginx configuration in the module code as a reference to what else
should be configured.
You can use other web servers by forwarding calls for <filename>index.php</filename> and <filename>piwik.php</filename> to the <literal>/run/phpfpm-matomo.sock</literal> 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>

55
nixos/modules/services/web-apps/nextcloud.xml
View file

@ -5,21 +5,13 @@
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>.
<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>
<section xml:id="module-services-nextcloud-basic-usage">
<title>Basic usage</title>
<para>
Nextcloud is a PHP-based application which requires an HTTP server
(<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal>
optionally supports
<literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>)
and a database (it's recommended to use
<literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).
Nextcloud is a PHP-based application which requires an HTTP server (<literal><link linkend="opt-services.nextcloud.enable">services.nextcloud</link></literal> optionally supports <literal><link linkend="opt-services.nginx.enable">services.nginx</link></literal>) and a database (it's recommended to use <literal><link linkend="opt-services.postgresql.enable">services.postgresql</link></literal>).
</para>
<para>
@ -61,57 +53,38 @@
</para>
<para>
The options <literal>hostName</literal> and <literal>nginx.enable</literal>
are used internally to configure an HTTP server using
<literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal>
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.
The options <literal>hostName</literal> and <literal>nginx.enable</literal> are used internally to configure an HTTP server using <literal><link xlink:href="https://php-fpm.org/">PHP-FPM</link></literal> 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
<literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>)
it's needed to add them to
<literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.
In case the application serves multiple domains (those are checked with <literal><link xlink:href="http://php.net/manual/en/reserved.variables.server.php">$_SERVER['HTTP_HOST']</link></literal>) it's needed to add them to <literal><link linkend="opt-services.nextcloud.config.extraTrustedDomains">services.nextcloud.config.extraTrustedDomains</link></literal>.
</para>
<para>
Auto updates for Nextcloud apps can be enabled using
<literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>.
</para>
Auto updates for Nextcloud apps can be enabled using <literal><link linkend="opt-services.nextcloud.autoUpdateApps.enable">services.nextcloud.autoUpdateApps</link></literal>.
</para>
</section>
<section xml:id="module-services-nextcloud-pitfalls-during-upgrade">
<title>Pitfalls</title>
<para>
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).
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
<literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by
the module and linked from the store to ensure that all values from <literal>config.php</literal>
can be modified by the module.
However <literal>config.php</literal> manages the application's state and shouldn't be touched
manually because of that.
All configuration parameters are also stored in <literal>/var/lib/nextcloud/config/override.config.php</literal> which is generated by the module and linked from the store to ensure that all values from <literal>config.php</literal> can be modified by the module. However <literal>config.php</literal> manages the application's state and shouldn't be touched manually because of that.
</para>
<warning>
<para>Don't delete <literal>config.php</literal>! This file
tracks the application's state and a deletion can cause unwanted
side-effects!</para>
<para>
Don't delete <literal>config.php</literal>! 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>
<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>
</section>
</chapter>