From 642854055c4315978dd470aa8eeb06b5333cdfa3 Mon Sep 17 00:00:00 2001 From: talyz Date: Mon, 15 Mar 2021 16:55:05 +0100 Subject: [PATCH] nixos/discourse: Add NixOS manual entry --- nixos/modules/services/web-apps/discourse.nix | 3 + nixos/modules/services/web-apps/discourse.xml | 323 ++++++++++++++++++ 2 files changed, 326 insertions(+) create mode 100644 nixos/modules/services/web-apps/discourse.xml diff --git a/nixos/modules/services/web-apps/discourse.nix b/nixos/modules/services/web-apps/discourse.nix index 6f4c50006d3e..03ea002c9dee 100644 --- a/nixos/modules/services/web-apps/discourse.nix +++ b/nixos/modules/services/web-apps/discourse.nix @@ -1029,4 +1029,7 @@ in cfg.package.rake ]; }; + + meta.doc = ./discourse.xml; + meta.maintainers = [ lib.maintainers.talyz ]; } diff --git a/nixos/modules/services/web-apps/discourse.xml b/nixos/modules/services/web-apps/discourse.xml new file mode 100644 index 000000000000..bae562423213 --- /dev/null +++ b/nixos/modules/services/web-apps/discourse.xml @@ -0,0 +1,323 @@ + + Discourse + + Discourse is a + modern and open source discussion platform. + + +
+ Basic usage + + A minimal configuration using Let's Encrypt for TLS certificates looks like this: + +services.discourse = { + enable = true; + hostname = "discourse.example.com"; + admin = { + email = "admin@example.com"; + username = "admin"; + fullName = "Administrator"; + passwordFile = "/path/to/password_file"; + }; + secretKeyBaseFile = "/path/to/secret_key_base_file"; +}; +security.acme.email = "me@example.com"; +security.acme.acceptTerms = true; + + + + + Provided a proper DNS setup, you'll be able to connect to the + instance at discourse.example.com and log in + using the credentials provided in + services.discourse.admin. + +
+ +
+ Using a regular TLS certificate + + To set up TLS using a regular certificate and key on file, use + the + and + options: + + +services.discourse = { + enable = true; + hostname = "discourse.example.com"; + sslCertificate = "/path/to/ssl_certificate"; + sslCertificateKey = "/path/to/ssl_certificate_key"; + admin = { + email = "admin@example.com"; + username = "admin"; + fullName = "Administrator"; + passwordFile = "/path/to/password_file"; + }; + secretKeyBaseFile = "/path/to/secret_key_base_file"; +}; + + + +
+ +
+ Database access + + Discourse uses + PostgreSQL to store most of its + data. A database will automatically be enabled and a database + and role created unless is changed from + its default of null or is set + to false. + + + + External database access can also be configured by setting + , and as + appropriate. Note that you need to manually create a database + called discourse (or the name you chose in + ) and + allow the configured database user full access to it. + +
+ +
+ Email + + In addition to the basic setup, you'll want to configure an SMTP + server Discourse can use to send user + registration and password reset emails, among others. You can + also optionally let Discourse receive + email, which enables people to reply to threads and conversations + via email. + + + + A basic setup which assumes you want to use your configured hostname as + email domain can be done like this: + + +services.discourse = { + enable = true; + hostname = "discourse.example.com"; + sslCertificate = "/path/to/ssl_certificate"; + sslCertificateKey = "/path/to/ssl_certificate_key"; + admin = { + email = "admin@example.com"; + username = "admin"; + fullName = "Administrator"; + passwordFile = "/path/to/password_file"; + }; + mail.outgoing = { + serverAddress = "smtp.emailprovider.com"; + port = 587; + username = "user@emailprovider.com"; + passwordFile = "/path/to/smtp_password_file"; + }; + mail.incoming.enable = true; + secretKeyBaseFile = "/path/to/secret_key_base_file"; +}; + + + This assumes you have set up an MX record for the address you've + set in hostname and + requires proper SPF, DKIM and DMARC configuration to be done for + the domain you're sending from, in order for email to be reliably delivered. + + + + If you want to use a different domain for your outgoing email + (for example example.com instead of + discourse.example.com) you should set + and + manually. + + + + + Setup of TLS for incoming email is currently only configured + automatically when a regular TLS certificate is used, i.e. when + and + are + set. + + + +
+ +
+ Additional settings + + Additional site settings and backend settings, for which no + explicit NixOS options are provided, + can be set in and + respectively. + + +
+ Site settings + + Site settings are the settings that can be + changed through the Discourse + UI. Their default values can be set using + . + + + + Settings are expressed as a Nix attribute set which matches the + structure of the configuration in + config/site_settings.yml. + To find a setting's path, you only need to care about the first + two levels; i.e. its category (e.g. login) + and name (e.g. invite_only). + + + + Settings containing secret data should be set to an attribute + set containing the attribute _secret - a + string pointing to a file containing the value the option + should be set to. See the example. + +
+ +
+ Backend settings + + Settings are expressed as a Nix attribute set which matches the + structure of the configuration in + config/discourse.conf. + Empty parameters can be defined by setting them to + null. + +
+ +
+ Example + + The following example sets the title and description of the + Discourse instance and enables + GitHub login in the site settings, + and changes a few request limits in the backend settings: + +services.discourse = { + enable = true; + hostname = "discourse.example.com"; + sslCertificate = "/path/to/ssl_certificate"; + sslCertificateKey = "/path/to/ssl_certificate_key"; + admin = { + email = "admin@example.com"; + username = "admin"; + fullName = "Administrator"; + passwordFile = "/path/to/password_file"; + }; + mail.outgoing = { + serverAddress = "smtp.emailprovider.com"; + port = 587; + username = "user@emailprovider.com"; + passwordFile = "/path/to/smtp_password_file"; + }; + mail.incoming.enable = true; + siteSettings = { + required = { + title = "My Cats"; + site_description = "Discuss My Cats (and be nice plz)"; + }; + login = { + enable_github_logins = true; + github_client_id = "a2f6dfe838cb3206ce20"; + github_client_secret._secret = /run/keys/discourse_github_client_secret; + }; + }; + backendSettings = { + max_reqs_per_ip_per_minute = 300; + max_reqs_per_ip_per_10_seconds = 60; + max_asset_reqs_per_ip_per_10_seconds = 250; + max_reqs_per_ip_mode = "warn+block"; + }; + secretKeyBaseFile = "/path/to/secret_key_base_file"; +}; + + + + In the resulting site settings file, the + login.github_client_secret key will be set + to the contents of the + /run/keys/discourse_github_client_secret + file. + +
+
+
+ Plugins + + You can install Discourse plugins + using the + option. As long as a plugin supports the standard install + method, packaging it should only require fetching its source + with an appropriate fetcher. + + + + Some plugins provide site + settings. Their defaults can be configured using , just like + regular site settings. To find the names of these settings, look + in the config/settings.yml file of the plugin + repo. + + + + For example, to add the discourse-spoiler-alert + plugin and disable it by default: + + +services.discourse = { + enable = true; + hostname = "discourse.example.com"; + sslCertificate = "/path/to/ssl_certificate"; + sslCertificateKey = "/path/to/ssl_certificate_key"; + admin = { + email = "admin@example.com"; + username = "admin"; + fullName = "Administrator"; + passwordFile = "/path/to/password_file"; + }; + mail.outgoing = { + serverAddress = "smtp.emailprovider.com"; + port = 587; + username = "user@emailprovider.com"; + passwordFile = "/path/to/smtp_password_file"; + }; + mail.incoming.enable = true; + plugins = [ + (pkgs.fetchFromGitHub { + owner = "discourse"; + repo = "discourse-spoiler-alert"; + rev = "e200cfa571d252cab63f3d30d619b370986e4cee"; + sha256 = "0ya69ix5g77wz4c9x9gmng6l25ghb5xxlx3icr6jam16q14dzc33"; + }) + ]; + siteSettings = { + plugins = { + spoiler_enabled = false; + }; + }; + secretKeyBaseFile = "/path/to/secret_key_base_file"; +}; + + + +
+