forked from mirrors/nixpkgs
nixos/discourse: Add NixOS manual entry
This commit is contained in:
talyz
parent
5138941ad3
commit
642854055c
|
|
@ -1029,4 +1029,7 @@ in
|
|||
cfg.package.rake
|
||||
];
|
||||
};
|
||||
|
||||
meta.doc = ./discourse.xml;
|
||||
meta.maintainers = [ lib.maintainers.talyz ];
|
||||
}
|
||||
|
|
|
|||
323
nixos/modules/services/web-apps/discourse.xml
Normal file
323
nixos/modules/services/web-apps/discourse.xml
Normal file
|
|
@ -0,0 +1,323 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="module-services-discourse">
|
||||
<title>Discourse</title>
|
||||
<para>
|
||||
<link xlink:href="https://www.discourse.org/">Discourse</link> is a
|
||||
modern and open source discussion platform.
|
||||
</para>
|
||||
|
||||
<section xml:id="module-services-discourse-basic-usage">
|
||||
<title>Basic usage</title>
|
||||
<para>
|
||||
A minimal configuration using Let's Encrypt for TLS certificates looks like this:
|
||||
<programlisting>
|
||||
services.discourse = {
|
||||
<link linkend="opt-services.discourse.enable">enable</link> = true;
|
||||
<link linkend="opt-services.discourse.hostname">hostname</link> = "discourse.example.com";
|
||||
admin = {
|
||||
<link linkend="opt-services.discourse.admin.email">email</link> = "admin@example.com";
|
||||
<link linkend="opt-services.discourse.admin.username">username</link> = "admin";
|
||||
<link linkend="opt-services.discourse.admin.fullName">fullName</link> = "Administrator";
|
||||
<link linkend="opt-services.discourse.admin.passwordFile">passwordFile</link> = "/path/to/password_file";
|
||||
};
|
||||
<link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";
|
||||
};
|
||||
<link linkend="opt-security.acme.email">security.acme.email</link> = "me@example.com";
|
||||
<link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Provided a proper DNS setup, you'll be able to connect to the
|
||||
instance at <literal>discourse.example.com</literal> and log in
|
||||
using the credentials provided in
|
||||
<literal>services.discourse.admin</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-discourse-tls">
|
||||
<title>Using a regular TLS certificate</title>
|
||||
<para>
|
||||
To set up TLS using a regular certificate and key on file, use
|
||||
the <xref linkend="opt-services.discourse.sslCertificate" />
|
||||
and <xref linkend="opt-services.discourse.sslCertificateKey" />
|
||||
options:
|
||||
|
||||
<programlisting>
|
||||
services.discourse = {
|
||||
<link linkend="opt-services.discourse.enable">enable</link> = true;
|
||||
<link linkend="opt-services.discourse.hostname">hostname</link> = "discourse.example.com";
|
||||
<link linkend="opt-services.discourse.sslCertificate">sslCertificate</link> = "/path/to/ssl_certificate";
|
||||
<link linkend="opt-services.discourse.sslCertificateKey">sslCertificateKey</link> = "/path/to/ssl_certificate_key";
|
||||
admin = {
|
||||
<link linkend="opt-services.discourse.admin.email">email</link> = "admin@example.com";
|
||||
<link linkend="opt-services.discourse.admin.username">username</link> = "admin";
|
||||
<link linkend="opt-services.discourse.admin.fullName">fullName</link> = "Administrator";
|
||||
<link linkend="opt-services.discourse.admin.passwordFile">passwordFile</link> = "/path/to/password_file";
|
||||
};
|
||||
<link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-discourse-database">
|
||||
<title>Database access</title>
|
||||
<para>
|
||||
<productname>Discourse</productname> uses
|
||||
<productname>PostgreSQL</productname> to store most of its
|
||||
data. A database will automatically be enabled and a database
|
||||
and role created unless <xref
|
||||
linkend="opt-services.discourse.database.host" /> is changed from
|
||||
its default of <literal>null</literal> or <xref
|
||||
linkend="opt-services.discourse.database.createLocally" /> is set
|
||||
to <literal>false</literal>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
External database access can also be configured by setting
|
||||
<xref linkend="opt-services.discourse.database.host" />, <xref
|
||||
linkend="opt-services.discourse.database.username" /> and <xref
|
||||
linkend="opt-services.discourse.database.passwordFile" /> as
|
||||
appropriate. Note that you need to manually create a database
|
||||
called <literal>discourse</literal> (or the name you chose in
|
||||
<xref linkend="opt-services.discourse.database.name" />) and
|
||||
allow the configured database user full access to it.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-discourse-mail">
|
||||
<title>Email</title>
|
||||
<para>
|
||||
In addition to the basic setup, you'll want to configure an SMTP
|
||||
server <productname>Discourse</productname> can use to send user
|
||||
registration and password reset emails, among others. You can
|
||||
also optionally let <productname>Discourse</productname> receive
|
||||
email, which enables people to reply to threads and conversations
|
||||
via email.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
A basic setup which assumes you want to use your configured <link
|
||||
linkend="opt-services.discourse.hostname">hostname</link> as
|
||||
email domain can be done like this:
|
||||
|
||||
<programlisting>
|
||||
services.discourse = {
|
||||
<link linkend="opt-services.discourse.enable">enable</link> = true;
|
||||
<link linkend="opt-services.discourse.hostname">hostname</link> = "discourse.example.com";
|
||||
<link linkend="opt-services.discourse.sslCertificate">sslCertificate</link> = "/path/to/ssl_certificate";
|
||||
<link linkend="opt-services.discourse.sslCertificateKey">sslCertificateKey</link> = "/path/to/ssl_certificate_key";
|
||||
admin = {
|
||||
<link linkend="opt-services.discourse.admin.email">email</link> = "admin@example.com";
|
||||
<link linkend="opt-services.discourse.admin.username">username</link> = "admin";
|
||||
<link linkend="opt-services.discourse.admin.fullName">fullName</link> = "Administrator";
|
||||
<link linkend="opt-services.discourse.admin.passwordFile">passwordFile</link> = "/path/to/password_file";
|
||||
};
|
||||
mail.outgoing = {
|
||||
<link linkend="opt-services.discourse.mail.outgoing.serverAddress">serverAddress</link> = "smtp.emailprovider.com";
|
||||
<link linkend="opt-services.discourse.mail.outgoing.port">port</link> = 587;
|
||||
<link linkend="opt-services.discourse.mail.outgoing.username">username</link> = "user@emailprovider.com";
|
||||
<link linkend="opt-services.discourse.mail.outgoing.passwordFile">passwordFile</link> = "/path/to/smtp_password_file";
|
||||
};
|
||||
<link linkend="opt-services.discourse.mail.incoming.enable">mail.incoming.enable</link> = true;
|
||||
<link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
This assumes you have set up an MX record for the address you've
|
||||
set in <link linkend="opt-services.discourse.hostname">hostname</link> and
|
||||
requires proper SPF, DKIM and DMARC configuration to be done for
|
||||
the domain you're sending from, in order for email to be reliably delivered.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If you want to use a different domain for your outgoing email
|
||||
(for example <literal>example.com</literal> instead of
|
||||
<literal>discourse.example.com</literal>) you should set
|
||||
<xref linkend="opt-services.discourse.mail.notificationEmailAddress" /> and
|
||||
<xref linkend="opt-services.discourse.mail.contactEmailAddress" /> manually.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
Setup of TLS for incoming email is currently only configured
|
||||
automatically when a regular TLS certificate is used, i.e. when
|
||||
<xref linkend="opt-services.discourse.sslCertificate" /> and
|
||||
<xref linkend="opt-services.discourse.sslCertificateKey" /> are
|
||||
set.
|
||||
</para>
|
||||
</note>
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-discourse-settings">
|
||||
<title>Additional settings</title>
|
||||
<para>
|
||||
Additional site settings and backend settings, for which no
|
||||
explicit <productname>NixOS</productname> options are provided,
|
||||
can be set in <xref linkend="opt-services.discourse.siteSettings" /> and
|
||||
<xref linkend="opt-services.discourse.backendSettings" /> respectively.
|
||||
</para>
|
||||
|
||||
<section xml:id="module-services-discourse-site-settings">
|
||||
<title>Site settings</title>
|
||||
<para>
|
||||
<quote>Site settings</quote> are the settings that can be
|
||||
changed through the <productname>Discourse</productname>
|
||||
UI. Their <emphasis>default</emphasis> values can be set using
|
||||
<xref linkend="opt-services.discourse.siteSettings" />.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Settings are expressed as a Nix attribute set which matches the
|
||||
structure of the configuration in
|
||||
<link xlink:href="https://github.com/discourse/discourse/blob/master/config/site_settings.yml">config/site_settings.yml</link>.
|
||||
To find a setting's path, you only need to care about the first
|
||||
two levels; i.e. its category (e.g. <literal>login</literal>)
|
||||
and name (e.g. <literal>invite_only</literal>).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Settings containing secret data should be set to an attribute
|
||||
set containing the attribute <literal>_secret</literal> - a
|
||||
string pointing to a file containing the value the option
|
||||
should be set to. See the example.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-discourse-backend-settings">
|
||||
<title>Backend settings</title>
|
||||
<para>
|
||||
Settings are expressed as a Nix attribute set which matches the
|
||||
structure of the configuration in
|
||||
<link xlink:href="https://github.com/discourse/discourse/blob/stable/config/discourse_defaults.conf">config/discourse.conf</link>.
|
||||
Empty parameters can be defined by setting them to
|
||||
<literal>null</literal>.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section xml:id="module-services-discourse-settings-example">
|
||||
<title>Example</title>
|
||||
<para>
|
||||
The following example sets the title and description of the
|
||||
<productname>Discourse</productname> instance and enables
|
||||
<productname>GitHub</productname> login in the site settings,
|
||||
and changes a few request limits in the backend settings:
|
||||
<programlisting>
|
||||
services.discourse = {
|
||||
<link linkend="opt-services.discourse.enable">enable</link> = true;
|
||||
<link linkend="opt-services.discourse.hostname">hostname</link> = "discourse.example.com";
|
||||
<link linkend="opt-services.discourse.sslCertificate">sslCertificate</link> = "/path/to/ssl_certificate";
|
||||
<link linkend="opt-services.discourse.sslCertificateKey">sslCertificateKey</link> = "/path/to/ssl_certificate_key";
|
||||
admin = {
|
||||
<link linkend="opt-services.discourse.admin.email">email</link> = "admin@example.com";
|
||||
<link linkend="opt-services.discourse.admin.username">username</link> = "admin";
|
||||
<link linkend="opt-services.discourse.admin.fullName">fullName</link> = "Administrator";
|
||||
<link linkend="opt-services.discourse.admin.passwordFile">passwordFile</link> = "/path/to/password_file";
|
||||
};
|
||||
mail.outgoing = {
|
||||
<link linkend="opt-services.discourse.mail.outgoing.serverAddress">serverAddress</link> = "smtp.emailprovider.com";
|
||||
<link linkend="opt-services.discourse.mail.outgoing.port">port</link> = 587;
|
||||
<link linkend="opt-services.discourse.mail.outgoing.username">username</link> = "user@emailprovider.com";
|
||||
<link linkend="opt-services.discourse.mail.outgoing.passwordFile">passwordFile</link> = "/path/to/smtp_password_file";
|
||||
};
|
||||
<link linkend="opt-services.discourse.mail.incoming.enable">mail.incoming.enable</link> = true;
|
||||
<link linkend="opt-services.discourse.siteSettings">siteSettings</link> = {
|
||||
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;
|
||||
};
|
||||
};
|
||||
<link linkend="opt-services.discourse.backendSettings">backendSettings</link> = {
|
||||
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";
|
||||
};
|
||||
<link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
<para>
|
||||
In the resulting site settings file, the
|
||||
<literal>login.github_client_secret</literal> key will be set
|
||||
to the contents of the
|
||||
<filename>/run/keys/discourse_github_client_secret</filename>
|
||||
file.
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
<section xml:id="module-services-discourse-plugins">
|
||||
<title>Plugins</title>
|
||||
<para>
|
||||
You can install <productname>Discourse</productname> plugins
|
||||
using the <xref linkend="opt-services.discourse.plugins" />
|
||||
option. As long as a plugin supports the standard install
|
||||
method, packaging it should only require fetching its source
|
||||
with an appropriate fetcher.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Some plugins provide <link
|
||||
linkend="module-services-discourse-site-settings">site
|
||||
settings</link>. Their defaults can be configured using <xref
|
||||
linkend="opt-services.discourse.siteSettings" />, just like
|
||||
regular site settings. To find the names of these settings, look
|
||||
in the <literal>config/settings.yml</literal> file of the plugin
|
||||
repo.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For example, to add the <link
|
||||
xlink:href="https://github.com/discourse/discourse-spoiler-alert">discourse-spoiler-alert</link>
|
||||
plugin and disable it by default:
|
||||
|
||||
<programlisting>
|
||||
services.discourse = {
|
||||
<link linkend="opt-services.discourse.enable">enable</link> = true;
|
||||
<link linkend="opt-services.discourse.hostname">hostname</link> = "discourse.example.com";
|
||||
<link linkend="opt-services.discourse.sslCertificate">sslCertificate</link> = "/path/to/ssl_certificate";
|
||||
<link linkend="opt-services.discourse.sslCertificateKey">sslCertificateKey</link> = "/path/to/ssl_certificate_key";
|
||||
admin = {
|
||||
<link linkend="opt-services.discourse.admin.email">email</link> = "admin@example.com";
|
||||
<link linkend="opt-services.discourse.admin.username">username</link> = "admin";
|
||||
<link linkend="opt-services.discourse.admin.fullName">fullName</link> = "Administrator";
|
||||
<link linkend="opt-services.discourse.admin.passwordFile">passwordFile</link> = "/path/to/password_file";
|
||||
};
|
||||
mail.outgoing = {
|
||||
<link linkend="opt-services.discourse.mail.outgoing.serverAddress">serverAddress</link> = "smtp.emailprovider.com";
|
||||
<link linkend="opt-services.discourse.mail.outgoing.port">port</link> = 587;
|
||||
<link linkend="opt-services.discourse.mail.outgoing.username">username</link> = "user@emailprovider.com";
|
||||
<link linkend="opt-services.discourse.mail.outgoing.passwordFile">passwordFile</link> = "/path/to/smtp_password_file";
|
||||
};
|
||||
<link linkend="opt-services.discourse.mail.incoming.enable">mail.incoming.enable</link> = true;
|
||||
<link linkend="opt-services.discourse.mail.incoming.enable">plugins</link> = [
|
||||
(pkgs.fetchFromGitHub {
|
||||
owner = "discourse";
|
||||
repo = "discourse-spoiler-alert";
|
||||
rev = "e200cfa571d252cab63f3d30d619b370986e4cee";
|
||||
sha256 = "0ya69ix5g77wz4c9x9gmng6l25ghb5xxlx3icr6jam16q14dzc33";
|
||||
})
|
||||
];
|
||||
<link linkend="opt-services.discourse.siteSettings">siteSettings</link> = {
|
||||
plugins = {
|
||||
spoiler_enabled = false;
|
||||
};
|
||||
};
|
||||
<link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
||||
Loading…
Reference in a new issue