danvics/selfhostblocks
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

fix documentation generation after update

Browse source 
https://github.com/NixOS/nixpkgs/pull/353513/files
This commit is contained in:
ibizaman 2024-11-21 21:22:36 +01:00
parent 5c25d74667
commit e05f0779b8
11 changed files with 1690 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
demo/homeassistant/README.md
View file

@ -60,7 +60,7 @@ chmod 600 sshkey
This is only needed because git mangles with the permissions. You will not even see this change in
`git status`.
### Deploy with Colmena {#demo-homeassitant-deploy-colmena}
### Deploy with Colmena {#demo-homeassistant-deploy-colmena}
If you deploy with Colmena, you must first build the VM and start it:

6
demo/nextcloud/README.md
View file

@ -112,7 +112,7 @@ ssh -F ssh_config example
:::: {.note}
This section corresponds to the `basic` section of the [Nextcloud
manual](services-nextcloud.html#services-nextcloud-server-usage-basic).
manual](services-nextcloud.html#services-nextcloudserver-usage-basic).
::::
Assuming you already deployed the `basic` demo, now you must add the following entry to the
@ -143,7 +143,7 @@ This is the admin user of Nextcloud and that's the end of the `basic` demo.
:::: {.note}
This section corresponds to the `ldap` section of the [Nextcloud
manual](services-nextcloud.html#services-nextcloud-server-usage-ldap).
manual](services-nextcloud.html#services-nextcloudserver-usage-ldap).
::::
Assuming you already deployed the `ldap` demo, now you must add the following entry to the
@ -182,7 +182,7 @@ This is the end of the `ldap` demo.
:::: {.note}
This section corresponds to the `sso` section of the [Nextcloud
manual](services-nextcloud.html#services-nextcloud-server-usage-oidc).
manual](services-nextcloud.html#services-nextcloudserver-usage-oidc).
::::
At this point, it is assumed you already deployed the `sso` demo. There is no host to add to

1
docs/default.nix
View file

@ -195,6 +195,7 @@ in stdenv.mkDerivation {
nixos-render-docs manual html \
--manpage-urls ${manpage-urls} \
--redirects ./redirects.json \
--media-dir media \
--revision ${lib.trivial.revisionWithDefault release} \
--stylesheet static/style.css \

2
docs/demos.md
View file

@ -7,6 +7,6 @@ your local machine with minimal manual steps.
demo/homeassistant/README.md
```
```{=include=} chapters html:into-file=//demo-nextcloud-server.html
```{=include=} chapters html:into-file=//demo-nextcloud.html
demo/nextcloud/README.md
```

2
docs/options.md
View file

@ -1,4 +1,4 @@
# All Options {#ch-options}
# All Options {#all-options}
```{=include=} options
id-prefix: opt-

1625
docs/redirects.json Normal file
View file

File diff suppressed because it is too large Load diff

14
modules/blocks/ssl/docs/default.md
View file

@ -1,4 +1,4 @@
# SSL Generator Block {#ssl-block}
# SSL Generator Block {#block-ssl}
This NixOS module is a block that implements the [SSL certificate generator](contracts-ssl.html) contract.
@ -14,7 +14,7 @@ It is implemented by:
[11]: blocks-ssl.html#blocks-ssl-options-shb.certs.certs.selfsigned
[12]: blocks-ssl.html#blocks-ssl-options-shb.certs.certs.letsencrypt
## Self-Signed Certificates {#ssl-block-impl-self-signed}
## Self-Signed Certificates {#block-ssl-impl-self-signed}
Defined in [`/modules/blocks/ssl.nix`](@REPO@/modules/blocks/ssl.nix).
@ -52,7 +52,7 @@ shb.certs.certs.selfsigned = {
The group has been chosen to be `nginx` to be consistent with the examples further down in this
document.
## Let's Encrypt {#ssl-block-impl-lets-encrypt}
## Let's Encrypt {#block-ssl-impl-lets-encrypt}
Defined in [`/modules/blocks/ssl.nix`](@REPO@/modules/blocks/ssl.nix).
@ -81,7 +81,7 @@ LINODE_TOKEN=XYZ...
For other providers, see the [official instruction](https://go-acme.github.io/lego/dns/).
## Usage {#ssl-block-usage}
## Usage {#block-ssl-usage}
To use either a self-signed certificates or a Let's Encrypt generated one, we can reference the path
where the certificate and the private key are located:
@ -110,16 +110,16 @@ config.shb.certs.systemdService
See also the [SSL certificate generator usage](contracts-ssl.html#ssl-contract-usage) for a more detailed usage
example.
## Debug {#ssl-block-debug}
## Debug {#block-ssl-debug}
Each CA and Cert is generated by a systemd service whose name can be seen in the `systemdService`
option. You can then see the latest errors messages using `journalctl`.
## Tests {#ssl-block-tests}
## Tests {#block-ssl-tests}
The self-signed implementation is tested in [`/tests/vm/ssl.nix`](@REPO@/tests/vm/ssl.nix).
## Options Reference {#ssl-block-options}
## Options Reference {#block-ssl-options}
```{=include=} options
id-prefix: blocks-ssl-options-

2
modules/contracts/backup/docs/default.md
View file

@ -101,6 +101,6 @@ Or with another module `backupservice_2`!
- <!-- [ -->Home Assistant<!--](services-home-assistant.html). --> (no manual yet)
- <!-- [ -->Jellyfin<!--](services-jellyfin.html). --> (no manual yet)
- <!-- [ -->LLDAP<!--](blocks-ldap.html). --> (no manual yet)
- [Nextcloud](services-nextcloud.html#services-nextcloud-server-usage-backup).
- [Nextcloud](services-nextcloud.html#services-nextcloudserver-usage-backup).
- [Vaultwarden](services-vaultwarden.html#services-vaultwarden-backup).
- <!-- [ -->*arr<!--](services-arr.html). --> (no manual yet)

14
modules/contracts/secret/docs/default.md
View file

@ -1,4 +1,4 @@
# Secret Contract {#secret-contract}
# Secret Contract {#contract-secret}
This NixOS contract represents a secret file
that must be created out of band - from outside the nix store -
@ -7,7 +7,7 @@ and that must be placed in an expected location with expected permission.
More formally, this contract is made between a requester module - the one needing a secret -
and a provider module - the one creating the secret and making it available.
## Motivation {#secret-contract-motivation}
## Motivation {#contract-secret-motivation}
Let's provide the [ldap SHB module][ldap-module] option `ldapUserPasswordFile`
with a secret managed by [sops-nix][].
@ -68,7 +68,7 @@ shb.sops.secrets."ldap/user_password".request = config.shb.ldap.userPassword.req
shb.ldap.userPassword.result = config.shb.sops.secrets."ldap/user_password".result;
```
## Contract Reference {#secret-contract-options}
## Contract Reference {#contract-secret-options}
These are all the options that are expected to exist for this contract to be respected.
@ -78,7 +78,7 @@ list-id: selfhostblocks-options
source: @OPTIONS_JSON@
```
## Usage {#secret-contract-usage}
## Usage {#contract-secret-usage}
A contract involves 3 parties:
@ -88,7 +88,7 @@ A contract involves 3 parties:
The usage of this contract is similarly separated into 3 sections.
### Requester Module {#secret-contract-usage-requester}
### Requester Module {#contract-secret-usage-requester}
Here is an example module requesting two secrets through the `secret` contract.
@ -128,7 +128,7 @@ in
};
```
### Provider Module {#secret-contract-usage-provider}
### Provider Module {#contract-secret-usage-provider}
Now, on the other side, we have a module that uses those options and provides a secret.
Let's assume such a module is available under the `secretservice` option
@ -177,7 +177,7 @@ in
}
```
### End User {#secret-contract-usage-enduser}
### End User {#contract-secret-usage-enduser}
The end user's responsibility is now to do some plumbing.

10
modules/contracts/ssl/docs/default.md
View file

@ -1,10 +1,10 @@
# SSL Generator Contract {#ssl-contract}
# SSL Generator Contract {#contract-ssl}
This NixOS contract represents an SSL certificate generator. This contract is used to decouple
generating an SSL certificate from using it. In practice, you can swap generators without updating
modules depending on it.
## Contract Reference {#ssl-contract-options}
## Contract Reference {#contract-ssl-options}
These are all the options that are expected to exist for this contract to be respected.
@ -14,7 +14,7 @@ list-id: selfhostblocks-options
source: @OPTIONS_JSON@
```
## Usage {#ssl-contract-usage}
## Usage {#contract-ssl-usage}
Let's assume a module implementing this contract is available under the `ssl` variable:
@ -56,11 +56,11 @@ systemd.services.nginx = {
};
```
## Provided Implementations {#ssl-contract-impl-shb}
## Provided Implementations {#contract-ssl-impl-shb}
Multiple implementation are provided out of the box at [SSL block](blocks-ssl.html).
## Custom Implementation {#ssl-contract-impl-custom}
## Custom Implementation {#contract-ssl-impl-custom}
To implement this contract, you must create a module that respects this contract. The following
snippet shows an example.

76
modules/services/nextcloud-server/docs/default.md
View file

@ -1,27 +1,27 @@
# Nextcloud Server Service {#services-nextcloud-server}
# Nextcloud Server Service {#services-nextcloudserver}
Defined in [`/modules/services/nextcloud-server.nix`](@REPO@/modules/services/nextcloud-server.nix).
This NixOS module is a service that sets up a [Nextcloud Server](https://nextcloud.com/).
It is based on the nixpkgs Nextcloud server and provides opinionated defaults.
## Features {#services-nextcloud-server-features}
## Features {#services-nextcloudserver-features}
- Declarative [Apps](#services-nextcloud-server-options-shb.nextcloud.apps) Configuration - no need
- Declarative [Apps](#services-nextcloudserver-options-shb.nextcloud.apps) Configuration - no need
to configure those with the UI.
- [LDAP](#services-nextcloud-server-usage-ldap) app:
- [LDAP](#services-nextcloudserver-usage-ldap) app:
enables app and sets up integration with an existing LDAP server, in this case LLDAP.
- [SSO](#services-nextcloud-server-usage-oidc) app:
- [SSO](#services-nextcloudserver-usage-oidc) app:
enables app and sets up integration with an existing SSO server, in this case Authelia.
- [Preview Generator](#services-nextcloud-server-usage-previewgenerator) app:
- [Preview Generator](#services-nextcloudserver-usage-previewgenerator) app:
enables app and sets up required cron job.
- [External Storage](#services-nextcloud-server-usage-externalstorage) app:
- [External Storage](#services-nextcloudserver-usage-externalstorage) app:
enables app and optionally configures one local mount.
This enables having data living on separate hard drives.
- [Only Office](#services-nextcloud-server-usage-onlyoffice) app:
- [Only Office](#services-nextcloudserver-usage-onlyoffice) app:
enables app and sets up Only Office service.
- Any other app through the
[shb.nextcloud.extraApps](#services-nextcloud-server-options-shb.nextcloud.extraApps) option.
[shb.nextcloud.extraApps](#services-nextcloudserver-options-shb.nextcloud.extraApps) option.
- Access through subdomain using reverse proxy.
- Forces Nginx as the reverse proxy. (This is hardcoded in the upstream nixpkgs module).
- Sets good defaults for trusted proxies settings, chunk size, opcache php options.
@ -40,15 +40,15 @@ It is based on the nixpkgs Nextcloud server and provides opinionated defaults.
- By default automatically disables maintenance mode on start.
- By default automatically launches repair mode with expensive migrations on start.
- Access to advanced options not exposed here thanks to how NixOS modules work.
- Has a [demo](#services-nextcloud-server-demo).
- Has a [demo](#services-nextcloudserver-demo).
[dataDir]: ./services-nextcloud.html#services-nextcloud-server-options-shb.nextcloud.dataDir
[dataDir]: ./services-nextcloud.html#services-nextcloudserver-options-shb.nextcloud.dataDir
## Usage {#services-nextcloud-server-usage}
## Usage {#services-nextcloudserver-usage}
### Nextcloud through HTTP {#services-nextcloud-server-usage-basic}
### Nextcloud through HTTP {#services-nextcloudserver-usage-basic}
[HTTP]: #services-nextcloud-server-usage-basic
[HTTP]: #services-nextcloudserver-usage-basic
:::: {.note}
This section corresponds to the `basic` section of the [Nextcloud
@ -82,9 +82,9 @@ We will set that up in the next section.
You can now login as the admin user using the username `admin`
and the password defined in `sops.secrets."nextcloud/adminpass"`.
### Nextcloud through HTTPS {#services-nextcloud-server-usage-https}
### Nextcloud through HTTPS {#services-nextcloudserver-usage-https}
[HTTPS]: #services-nextcloud-server-usage-https
[HTTPS]: #services-nextcloudserver-usage-https
To setup HTTPS, we will get our certificates from Let's Encrypt using the HTTP method.
This is the easiest way to get started and does not require you to programmatically
@ -94,7 +94,7 @@ Under the hood, we use the Self Host Block [SSL contract](./contracts-ssl.html).
It allows the end user to choose how to generate the certificates.
If you want other options to generate the certificate, follow the SSL contract link.
Building upon the [Basic Configuration](#services-nextcloud-server-usage-basic) above, we add:
Building upon the [Basic Configuration](#services-nextcloudserver-usage-basic) above, we add:
```nix
shb.certs.certs.letsencrypt."example.com" = {
@ -111,17 +111,17 @@ shb.nextcloud = {
};
```
### Choose Nextcloud Version {#services-nextcloud-server-usage-version}
### Choose Nextcloud Version {#services-nextcloudserver-usage-version}
Self Host Blocks is conservative in the version of Nextcloud it's using.
To choose the version and upgrade at the time of your liking,
just use the [version](#services-nextcloud-server-options-shb.nextcloud.version) option:
just use the [version](#services-nextcloudserver-options-shb.nextcloud.version) option:
```nix
shb.nextcloud.version = 29;
```
### Mount Point {#services-nextcloud-server-usage-mount-point}
### Mount Point {#services-nextcloudserver-usage-mount-point}
If the `dataDir` exists in a mount point,
it is highly recommended to make the various Nextcloud services wait on the mount point before starting.
@ -134,9 +134,9 @@ fileSystems."/var".device = "...";
shb.nextcloud.mountPointServices = [ "var.mount" ];
```
### With LDAP Support {#services-nextcloud-server-usage-ldap}
### With LDAP Support {#services-nextcloudserver-usage-ldap}
[LDAP]: #services-nextcloud-server-usage-ldap
[LDAP]: #services-nextcloudserver-usage-ldap
:::: {.note}
This section corresponds to the `ldap` section of the [Nextcloud
@ -206,7 +206,7 @@ so you need to create a normal user like above,
login with it once so it is known to Nextcloud, then logout,
login with the admin Nextcloud user and promote that new user to admin level.
### With SSO Support {#services-nextcloud-server-usage-oidc}
### With SSO Support {#services-nextcloudserver-usage-oidc}
:::: {.note}
This section corresponds to the `sso` section of the [Nextcloud
@ -289,7 +289,7 @@ secrets have the same content.
Setting the `fallbackDefaultAuth` to `false` means the only way to login is through Authelia.
If this does not work for any reason, you can let users login through Nextcloud directly by setting this option to `true`.
### Tweak PHPFpm Config {#services-nextcloud-server-usage-phpfpm}
### Tweak PHPFpm Config {#services-nextcloudserver-usage-phpfpm}
For instances with more users, or if you feel the pages are loading slowly,
you can tweak the `php-fpm` pool settings.
@ -311,7 +311,7 @@ I don't have a good heuristic for what are good values here but what I found
is that you don't want too high of a `max_children` value
to avoid I/O strain on the hard drives, especially if you use spinning drives.
### Tweak PostgreSQL Settings {#services-nextcloud-server-usage-postgres}
### Tweak PostgreSQL Settings {#services-nextcloudserver-usage-postgres}
These settings will impact all databases since the NixOS Postgres module
configures only one Postgres instance.
@ -353,7 +353,7 @@ shb.nextcloud.postgresSettings = {
};
```
### Backup {#services-nextcloud-server-usage-backup}
### Backup {#services-nextcloudserver-usage-backup}
Backing up Nextcloud data files using the [Restic block](blocks-restic.html) is done like so:
@ -385,7 +385,7 @@ Note that this will backup the whole PostgreSQL instance,
not just the Nextcloud database.
This limitation will be lifted in the future.
### Enable Preview Generator App {#services-nextcloud-server-usage-previewgenerator}
### Enable Preview Generator App {#services-nextcloudserver-usage-previewgenerator}
The following snippet installs and enables the [Preview
Generator](https://apps.nextcloud.com/apps/previewgenerator) application as well as creates the
@ -410,7 +410,7 @@ You can opt-out with:
shb.nextcloud.apps.previewgenerator.recommendedSettings = false;
```
### Enable External Storage App {#services-nextcloud-server-usage-externalstorage}
### Enable External Storage App {#services-nextcloudserver-usage-externalstorage}
The following snippet installs and enables the [External
Storage](https://docs.nextcloud.com/server/28/go.php?to=admin-external-storage) application.
@ -447,7 +447,7 @@ which is well suited for randomly accessing small files like thumbnails.
On the other side, a spinning hard drive can store more data
which is well suited for storing user data.
### Enable OnlyOffice App {#services-nextcloud-server-usage-onlyoffice}
### Enable OnlyOffice App {#services-nextcloudserver-usage-onlyoffice}
The following snippet installs and enables the [Only
Office](https://apps.nextcloud.com/apps/onlyoffice) application as well as sets up an Only Office
@ -469,7 +469,7 @@ nixpkgs.config.allowUnfreePredicate = pkg: builtins.elem (pkgs.lib.getName pkg)
];
```
### Enable Monitoring {#services-nextcloud-server-server-usage-monitoring}
### Enable Monitoring {#services-nextcloudserver-server-usage-monitoring}
Enable the [monitoring block](./blocks-monitoring.html).
A [Grafana dashboard][] for overall server performance will be created
@ -477,7 +477,7 @@ and the Nextcloud metrics will automatically appear there.
[Grafana dashboard]: ./blocks-monitoring.html#blocks-monitoring-performance-dashboard
### Enable Tracing {#services-nextcloud-server-server-usage-tracing}
### Enable Tracing {#services-nextcloudserver-server-usage-tracing}
You can enable tracing with:
@ -492,7 +492,7 @@ but that's not the case yet.
[my blog post]: http://blog.tiserbox.com/posts/2023-08-12-what%27s-up-with-nextcloud-webdav-slowness.html
### Appdata Location {#services-nextcloud-server-server-usage-appdata}
### Appdata Location {#services-nextcloudserver-server-usage-appdata}
The appdata folder is a special folder located under the `shb.nextcloud.dataDir` directory.
It is named `appdata_<instanceid>` with the Nextcloud's instance ID as a suffix.
@ -503,7 +503,7 @@ For performance reasons, it is recommended to store this folder on a fast drive
that is optimized for randomized read and write access.
The best would be either an SSD or an NVMe drive.
The best way to solve this is to use the [External Storage app](#services-nextcloud-server-usage-externalstorage).
The best way to solve this is to use the [External Storage app](#services-nextcloudserver-usage-externalstorage).
If you have an existing installation and put Nextcloud's `shb.nextcloud.dataDir` folder on a HDD with spinning disks,
then the appdata folder is also located on spinning drives.
@ -521,16 +521,16 @@ mount --bind /srv/sdd/appdata_nextcloud /var/lib/nextcloud/data/appdata_ocxvky2f
Note that you can re-generate a new appdata folder
by issuing the command `nextcloud-occ config:system:delete instanceid`.
## Demo {#services-nextcloud-server-demo}
## Demo {#services-nextcloudserver-demo}
Head over to the [Nextcloud demo](demo-nextcloud-server.html) for a demo that installs Nextcloud with or
without LDAP integration on a VM with minimal manual steps.
## Maintenance {#services-nextcloud-server-maintenance}
## Maintenance {#services-nextcloudserver-maintenance}
On the command line, the `occ` tool is called `nextcloud-occ`.
## Debug {#services-nextcloud-server-debug}
## Debug {#services-nextcloudserver-debug}
In case of an issue, check the logs for any systemd service mentioned in this section.
@ -547,10 +547,10 @@ Access the database with `sudo -u nextcloud psql`.
Access Redis with `sudo -u nextcloud redis-cli -s /run/redis-nextcloud/redis.sock`.
## Options Reference {#services-nextcloud-server-options}
## Options Reference {#services-nextcloudserver-options}
```{=include=} options
id-prefix: services-nextcloud-server-options-
id-prefix: services-nextcloudserver-options-
list-id: selfhostblocks-service-nextcloud-options
source: @OPTIONS_JSON@
```