# Discourse {#module-services-discourse}

[Discourse](https://www.discourse.org/) is a
modern and open source discussion platform.

## Basic usage {#module-services-discourse-basic-usage}

A minimal configuration using Let's Encrypt for TLS certificates looks like this:
```nix
{
  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 {#module-services-discourse-tls}

To set up TLS using a regular certificate and key on file, use
the [](#opt-services.discourse.sslCertificate)
and [](#opt-services.discourse.sslCertificateKey)
options:

```nix
{
  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 {#module-services-discourse-database}

Discourse uses PostgreSQL to store most of its
data. A database will automatically be enabled and a database
and role created unless [](#opt-services.discourse.database.host) is changed from
its default of `null` or [](#opt-services.discourse.database.createLocally) is set
to `false`.

External database access can also be configured by setting
[](#opt-services.discourse.database.host),
[](#opt-services.discourse.database.username) and
[](#opt-services.discourse.database.passwordFile) as
appropriate. Note that you need to manually create a database
called `discourse` (or the name you chose in
[](#opt-services.discourse.database.name)) and
allow the configured database user full access to it.

## Email {#module-services-discourse-mail}

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](#opt-services.discourse.hostname) as
email domain can be done like this:

```nix
{
  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](#opt-services.discourse.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
[](#opt-services.discourse.mail.notificationEmailAddress) and
[](#opt-services.discourse.mail.contactEmailAddress) manually.

::: {.note}
Setup of TLS for incoming email is currently only configured