mirror of
https://github.com/NixOS/nixpkgs.git
synced 2025-01-29 08:14:19 +00:00
332 lines
13 KiB
XML
332 lines
13 KiB
XML
<!-- Do not edit this file directly, edit its companion .md instead
|
||
and regenerate this file using nixos/doc/manual/md-to-db.sh -->
|
||
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-discourse">
|
||
<title>Discourse</title>
|
||
<para>
|
||
<link xlink:href="https://www.discourse.org/">Discourse</link> is a
|
||
modern and open source discussion platform.
|
||
</para>
|
||
<section xml:id="module-services-discourse-basic-usage">
|
||
<title>Basic usage</title>
|
||
<para>
|
||
A minimal configuration using Let’s Encrypt for TLS certificates
|
||
looks like this:
|
||
</para>
|
||
<programlisting>
|
||
services.discourse = {
|
||
enable = true;
|
||
hostname = "discourse.example.com";
|
||
admin = {
|
||
email = "admin@example.com";
|
||
username = "admin";
|
||
fullName = "Administrator";
|
||
passwordFile = "/path/to/password_file";
|
||
};
|
||
secretKeyBaseFile = "/path/to/secret_key_base_file";
|
||
};
|
||
security.acme.email = "me@example.com";
|
||
security.acme.acceptTerms = true;
|
||
</programlisting>
|
||
<para>
|
||
Provided a proper DNS setup, you’ll be able to connect to the
|
||
instance at <literal>discourse.example.com</literal> and log in
|
||
using the credentials provided in
|
||
<literal>services.discourse.admin</literal>.
|
||
</para>
|
||
</section>
|
||
<section xml:id="module-services-discourse-tls">
|
||
<title>Using a regular TLS certificate</title>
|
||
<para>
|
||
To set up TLS using a regular certificate and key on file, use the
|
||
<xref linkend="opt-services.discourse.sslCertificate" /> and
|
||
<xref linkend="opt-services.discourse.sslCertificateKey" />
|
||
options:
|
||
</para>
|
||
<programlisting>
|
||
services.discourse = {
|
||
enable = true;
|
||
hostname = "discourse.example.com";
|
||
sslCertificate = "/path/to/ssl_certificate";
|
||
sslCertificateKey = "/path/to/ssl_certificate_key";
|
||
admin = {
|
||
email = "admin@example.com";
|
||
username = "admin";
|
||
fullName = "Administrator";
|
||
passwordFile = "/path/to/password_file";
|
||
};
|
||
secretKeyBaseFile = "/path/to/secret_key_base_file";
|
||
};
|
||
</programlisting>
|
||
</section>
|
||
<section xml:id="module-services-discourse-database">
|
||
<title>Database access</title>
|
||
<para>
|
||
Discourse uses PostgreSQL to store most of its data. A database
|
||
will automatically be enabled and a database and role created
|
||
unless <xref linkend="opt-services.discourse.database.host" /> is
|
||
changed from its default of <literal>null</literal> or
|
||
<xref linkend="opt-services.discourse.database.createLocally" />
|
||
is set to <literal>false</literal>.
|
||
</para>
|
||
<para>
|
||
External database access can also be configured by setting
|
||
<xref linkend="opt-services.discourse.database.host" />,
|
||
<xref linkend="opt-services.discourse.database.username" /> and
|
||
<xref linkend="opt-services.discourse.database.passwordFile" /> as
|
||
appropriate. Note that you need to manually create a database
|
||
called <literal>discourse</literal> (or the name you chose in
|
||
<xref linkend="opt-services.discourse.database.name" />) and allow
|
||
the configured database user full access to it.
|
||
</para>
|
||
</section>
|
||
<section xml:id="module-services-discourse-mail">
|
||
<title>Email</title>
|
||
<para>
|
||
In addition to the basic setup, you’ll want to configure an SMTP
|
||
server Discourse can use to send user registration and password
|
||
reset emails, among others. You can also optionally let Discourse
|
||
receive email, which enables people to reply to threads and
|
||
conversations via email.
|
||
</para>
|
||
<para>
|
||
A basic setup which assumes you want to use your configured
|
||
<link linkend="opt-services.discourse.hostname">hostname</link> as
|
||
email domain can be done like this:
|
||
</para>
|
||
<programlisting>
|
||
services.discourse = {
|
||
enable = true;
|
||
hostname = "discourse.example.com";
|
||
sslCertificate = "/path/to/ssl_certificate";
|
||
sslCertificateKey = "/path/to/ssl_certificate_key";
|
||
admin = {
|
||
email = "admin@example.com";
|
||
username = "admin";
|
||
fullName = "Administrator";
|
||
passwordFile = "/path/to/password_file";
|
||
};
|
||
mail.outgoing = {
|
||
serverAddress = "smtp.emailprovider.com";
|
||
port = 587;
|
||
username = "user@emailprovider.com";
|
||
passwordFile = "/path/to/smtp_password_file";
|
||
};
|
||
mail.incoming.enable = true;
|
||
secretKeyBaseFile = "/path/to/secret_key_base_file";
|
||
};
|
||
</programlisting>
|
||
<para>
|
||
This assumes you have set up an MX record for the address you’ve
|
||
set in
|
||
<link linkend="opt-services.discourse.hostname">hostname</link>
|
||
and requires proper SPF, DKIM and DMARC configuration to be done
|
||
for the domain you’re sending from, in order for email to be
|
||
reliably delivered.
|
||
</para>
|
||
<para>
|
||
If you want to use a different domain for your outgoing email (for
|
||
example <literal>example.com</literal> instead of
|
||
<literal>discourse.example.com</literal>) you should set
|
||
<xref linkend="opt-services.discourse.mail.notificationEmailAddress" />
|
||
and
|
||
<xref linkend="opt-services.discourse.mail.contactEmailAddress" />
|
||
manually.
|
||
</para>
|
||
<note>
|
||
<para>
|
||
Setup of TLS for incoming email is currently only configured
|
||
automatically when a regular TLS certificate is used, i.e. when
|
||
<xref linkend="opt-services.discourse.sslCertificate" /> and
|
||
<xref linkend="opt-services.discourse.sslCertificateKey" /> are
|
||
set.
|
||
</para>
|
||
</note>
|
||
</section>
|
||
<section xml:id="module-services-discourse-settings">
|
||
<title>Additional settings</title>
|
||
<para>
|
||
Additional site settings and backend settings, for which no
|
||
explicit NixOS options are provided, can be set in
|
||
<xref linkend="opt-services.discourse.siteSettings" /> and
|
||
<xref linkend="opt-services.discourse.backendSettings" />
|
||
respectively.
|
||
</para>
|
||
<section xml:id="module-services-discourse-site-settings">
|
||
<title>Site settings</title>
|
||
<para>
|
||
<quote>Site settings</quote> are the settings that can be
|
||
changed through the Discourse UI. Their
|
||
<emphasis>default</emphasis> values can be set using
|
||
<xref linkend="opt-services.discourse.siteSettings" />.
|
||
</para>
|
||
<para>
|
||
Settings are expressed as a Nix attribute set which matches the
|
||
structure of the configuration in
|
||
<link xlink:href="https://github.com/discourse/discourse/blob/master/config/site_settings.yml">config/site_settings.yml</link>.
|
||
To find a setting’s path, you only need to care about the first
|
||
two levels; i.e. its category (e.g. <literal>login</literal>)
|
||
and name (e.g. <literal>invite_only</literal>).
|
||
</para>
|
||
<para>
|
||
Settings containing secret data should be set to an attribute
|
||
set containing the attribute <literal>_secret</literal> - a
|
||
string pointing to a file containing the value the option should
|
||
be set to. See the example.
|
||
</para>
|
||
</section>
|
||
<section xml:id="module-services-discourse-backend-settings">
|
||
<title>Backend settings</title>
|
||
<para>
|
||
Settings are expressed as a Nix attribute set which matches the
|
||
structure of the configuration in
|
||
<link xlink:href="https://github.com/discourse/discourse/blob/stable/config/discourse_defaults.conf">config/discourse.conf</link>.
|
||
Empty parameters can be defined by setting them to
|
||
<literal>null</literal>.
|
||
</para>
|
||
</section>
|
||
<section xml:id="module-services-discourse-settings-example">
|
||
<title>Example</title>
|
||
<para>
|
||
The following example sets the title and description of the
|
||
Discourse instance and enables GitHub login in the site
|
||
settings, and changes a few request limits in the backend
|
||
settings:
|
||
</para>
|
||
<programlisting>
|
||
services.discourse = {
|
||
enable = true;
|
||
hostname = "discourse.example.com";
|
||
sslCertificate = "/path/to/ssl_certificate";
|
||
sslCertificateKey = "/path/to/ssl_certificate_key";
|
||
admin = {
|
||
email = "admin@example.com";
|
||
username = "admin";
|
||
fullName = "Administrator";
|
||
passwordFile = "/path/to/password_file";
|
||
};
|
||
mail.outgoing = {
|
||
serverAddress = "smtp.emailprovider.com";
|
||
port = 587;
|
||
username = "user@emailprovider.com";
|
||
passwordFile = "/path/to/smtp_password_file";
|
||
};
|
||
mail.incoming.enable = true;
|
||
siteSettings = {
|
||
required = {
|
||
title = "My Cats";
|
||
site_description = "Discuss My Cats (and be nice plz)";
|
||
};
|
||
login = {
|
||
enable_github_logins = true;
|
||
github_client_id = "a2f6dfe838cb3206ce20";
|
||
github_client_secret._secret = /run/keys/discourse_github_client_secret;
|
||
};
|
||
};
|
||
backendSettings = {
|
||
max_reqs_per_ip_per_minute = 300;
|
||
max_reqs_per_ip_per_10_seconds = 60;
|
||
max_asset_reqs_per_ip_per_10_seconds = 250;
|
||
max_reqs_per_ip_mode = "warn+block";
|
||
};
|
||
secretKeyBaseFile = "/path/to/secret_key_base_file";
|
||
};
|
||
</programlisting>
|
||
<para>
|
||
In the resulting site settings file, the
|
||
<literal>login.github_client_secret</literal> key will be set to
|
||
the contents of the
|
||
<filename>/run/keys/discourse_github_client_secret</filename>
|
||
file.
|
||
</para>
|
||
</section>
|
||
</section>
|
||
<section xml:id="module-services-discourse-plugins">
|
||
<title>Plugins</title>
|
||
<para>
|
||
You can install Discourse plugins using the
|
||
<xref linkend="opt-services.discourse.plugins" /> option.
|
||
Pre-packaged plugins are provided in
|
||
<literal><your_discourse_package_here>.plugins</literal>. If
|
||
you want the full suite of plugins provided through
|
||
<literal>nixpkgs</literal>, you can also set the
|
||
<xref linkend="opt-services.discourse.package" /> option to
|
||
<literal>pkgs.discourseAllPlugins</literal>.
|
||
</para>
|
||
<para>
|
||
Plugins can be built with the
|
||
<literal><your_discourse_package_here>.mkDiscoursePlugin</literal>
|
||
function. Normally, it should suffice to provide a
|
||
<literal>name</literal> and <literal>src</literal> attribute. If
|
||
the plugin has Ruby dependencies, however, they need to be
|
||
packaged in accordance with the
|
||
<link xlink:href="https://nixos.org/manual/nixpkgs/stable/#developing-with-ruby">Developing
|
||
with Ruby</link> section of the Nixpkgs manual and the appropriate
|
||
gem options set in <literal>bundlerEnvArgs</literal> (normally
|
||
<literal>gemdir</literal> is sufficient). A plugin’s Ruby
|
||
dependencies are listed in its <filename>plugin.rb</filename> file
|
||
as function calls to <literal>gem</literal>. To construct the
|
||
corresponding <filename>Gemfile</filename> manually, run
|
||
<command>bundle init</command>, then add the
|
||
<literal>gem</literal> lines to it verbatim.
|
||
</para>
|
||
<para>
|
||
Much of the packaging can be done automatically by the
|
||
<filename>nixpkgs/pkgs/servers/web-apps/discourse/update.py</filename>
|
||
script - just add the plugin to the <literal>plugins</literal>
|
||
list in the <literal>update_plugins</literal> function and run the
|
||
script:
|
||
</para>
|
||
<programlisting language="bash">
|
||
./update.py update-plugins
|
||
</programlisting>
|
||
<para>
|
||
Some plugins provide
|
||
<link linkend="module-services-discourse-site-settings">site
|
||
settings</link>. Their defaults can be configured using
|
||
<xref linkend="opt-services.discourse.siteSettings" />, just like
|
||
regular site settings. To find the names of these settings, look
|
||
in the <literal>config/settings.yml</literal> file of the plugin
|
||
repo.
|
||
</para>
|
||
<para>
|
||
For example, to add the
|
||
<link xlink:href="https://github.com/discourse/discourse-spoiler-alert">discourse-spoiler-alert</link>
|
||
and
|
||
<link xlink:href="https://github.com/discourse/discourse-solved">discourse-solved</link>
|
||
plugins, and disable <literal>discourse-spoiler-alert</literal> by
|
||
default:
|
||
</para>
|
||
<programlisting>
|
||
services.discourse = {
|
||
enable = true;
|
||
hostname = "discourse.example.com";
|
||
sslCertificate = "/path/to/ssl_certificate";
|
||
sslCertificateKey = "/path/to/ssl_certificate_key";
|
||
admin = {
|
||
email = "admin@example.com";
|
||
username = "admin";
|
||
fullName = "Administrator";
|
||
passwordFile = "/path/to/password_file";
|
||
};
|
||
mail.outgoing = {
|
||
serverAddress = "smtp.emailprovider.com";
|
||
port = 587;
|
||
username = "user@emailprovider.com";
|
||
passwordFile = "/path/to/smtp_password_file";
|
||
};
|
||
mail.incoming.enable = true;
|
||
plugins = with config.services.discourse.package.plugins; [
|
||
discourse-spoiler-alert
|
||
discourse-solved
|
||
];
|
||
siteSettings = {
|
||
plugins = {
|
||
spoiler_enabled = false;
|
||
};
|
||
};
|
||
secretKeyBaseFile = "/path/to/secret_key_base_file";
|
||
};
|
||
</programlisting>
|
||
</section>
|
||
</chapter>
|