Installing and Configuring Discourse behind an Nginx Reverse Proxy on Debian 12 Bookworm: Complete Setup Blueprint

Prerequisites and Initial System Setup

This guide assumes a fresh Debian 12 (Bookworm) installation with root or sudo privileges. Essential packages for building and running Discourse, along with Nginx for reverse proxying, will be installed. We’ll also ensure the system is up-to-date.

Begin by updating your package lists and upgrading existing packages:

sudo apt update && sudo apt upgrade -y

Next, install necessary build tools, Git, and PostgreSQL, which Discourse relies on:

sudo apt install -y git postgresql postgresql-contrib curl build-essential libssl-dev libreadline-dev zlib1g-dev ruby-dev nodejs npm nginx

Discourse Installation via Docker

Discourse strongly recommends and officially supports installation via Docker. This simplifies dependency management and ensures a consistent environment. We’ll clone the official Discourse Docker image repository and configure it.

Create a directory for your Discourse installation and navigate into it:

mkdir /var/discourse
cd /var/discourse

Clone the Discourse Docker image repository:

git clone https://github.com/discourse/discourse_docker.git discourse

Navigate into the cloned directory:

cd discourse

Copy the sample configuration file:

cp samples/standalone.yml samples/app.yml

Now, edit the app.yml file to configure your Discourse instance. This is a critical step. You’ll need to set your domain name, email settings, and other parameters. Open the file with your preferred editor (e.g., nano):

nano samples/app.yml

Key parameters to modify within samples/app.yml:

• DISCOURSE_HOSTNAME: Set this to your fully qualified domain name (e.g., discourse.yourdomain.com).
• SMTP_ADDRESS, SMTP_PORT, SMTP_USER_NAME, SMTP_PASSWORD, SMTP_DOMAIN: Configure your outgoing SMTP server details for email notifications.
• MAILGUN_API_KEY, MAILGUN_DOMAIN: If using Mailgun for email, configure these.
• DB_HOST, DB_PORT, DB_USER, DB_PASS: These are for the PostgreSQL database. For a single-instance setup, defaults are usually fine, but ensure they are set if you’re using an external DB.
• REDIS_HOST, REDIS_PORT: For Redis. Defaults are usually fine for a single instance.
• ENABLE_LETSENCRYPT: Set to true if you want Discourse to manage SSL certificates via Let’s Encrypt. This is highly recommended for production.
• LETSENCRYPT_EMAIL: The email address for Let’s Encrypt notifications.

After saving the changes to app.yml, build and start your Discourse instance:

./launcher bootstrap app

This process can take a significant amount of time as it downloads Docker images and builds the Discourse application. Once complete, Discourse will be running, accessible on port 3000 of your server.

Nginx Reverse Proxy Configuration

To make Discourse accessible via your domain name and handle SSL termination, we’ll configure Nginx as a reverse proxy. Nginx is already installed from the prerequisite step.

Create a new Nginx configuration file for your Discourse instance. Replace discourse.yourdomain.com with your actual domain.

sudo nano /etc/nginx/sites-available/discourse

Paste the following configuration into the file. This configuration assumes you have enabled Let’s Encrypt in app.yml and Discourse will manage the certificates. If you are managing SSL certificates manually, adjust the ssl_certificate and ssl_certificate_key directives accordingly.

server {
    listen 80;
    listen [::]:80;
    server_name discourse.yourdomain.com; # Replace with your domain

    # Redirect HTTP to HTTPS
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name discourse.yourdomain.com; # Replace with your domain

    # SSL configuration managed by Discourse/LetsEncrypt
    # If managing manually, uncomment and set paths:
    # ssl_certificate /etc/letsencrypt/live/discourse.yourdomain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/discourse.yourdomain.com/privkey.pem;
    # include /etc/letsencrypt/options-ssl-nginx.conf;
    # ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;

    # Proxy settings
    location / {
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $http_host;
        proxy_set_header X-Forwarded-Host $host;
        proxy_pass http://127.0.0.1:3000; # Discourse default port
        proxy_read_timeout 300s;
        proxy_connect_timeout 75s;
        proxy_redirect off;
    }

    # Optional: Add headers for security and performance
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains; preload" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    # Optional: Enable Gzip compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;

    # Optional: Cache static assets
    location ~* ^/(assets|uploads|images)/ {
        expires 1y;
        add_header Cache-Control "public";
    }
}

Enable the new Nginx site and test the configuration:

sudo ln -s /etc/nginx/sites-available/discourse /etc/nginx/sites-enabled/
sudo nginx -t

If the test is successful, reload Nginx to apply the changes:

sudo systemctl reload nginx

Firewall Configuration (UFW)

Ensure your firewall allows traffic on ports 80 (HTTP) and 443 (HTTPS). If you are using UFW (Uncomplicated Firewall), configure it as follows:

sudo ufw allow 'Nginx Full'
sudo ufw enable

Verify the firewall status:

sudo ufw status

Initial Discourse Setup and Verification

After Nginx is reloaded and the firewall is configured, you should be able to access your Discourse instance by navigating to https://discourse.yourdomain.com in your web browser. The first time you access it, Discourse will guide you through the initial setup, including creating an administrator account.

If Let’s Encrypt was enabled in app.yml, it will automatically attempt to obtain and install SSL certificates. If this fails, you might need to manually run the Let’s Encrypt client or troubleshoot Nginx configuration and DNS records.

Managing Discourse with Docker

The discourse_docker directory provides several useful commands for managing your Discourse instance:

• ./launcher start app: Start the Discourse application.
• ./launcher stop app: Stop the Discourse application.
• ./launcher restart app: Restart the Discourse application.
• ./launcher rebuild app: Rebuild the Docker image and restart the application. Use this after updating app.yml or when applying Discourse updates.
• ./launcher logs app: View the logs for the Discourse application.
• ./launcher destroy app: Stop and remove the Discourse container.

To update Discourse to the latest version, navigate to the /var/discourse directory and run:

cd /var/discourse
git pull
./launcher rebuild app

This process will pull the latest code, rebuild the Docker image, and restart your Discourse instance with the updated version.

Advanced Nginx Tuning and Troubleshooting

For production environments, consider further Nginx tuning. You can adjust worker processes, buffer sizes, and caching strategies. Always test changes thoroughly.

If you encounter issues, check the following:

• DNS Resolution: Ensure your domain correctly points to your server’s IP address.
• Firewall Rules: Verify that ports 80 and 443 are open and accessible.
• Nginx Logs: Examine /var/log/nginx/error.log for Nginx-specific errors.
• Discourse Logs: Use ./launcher logs app within the /var/discourse directory for application-level errors.
• Docker Container Status: Check if the Discourse Docker container is running using docker ps.
• SSL Certificate Issues: If Let’s Encrypt fails, ensure your domain’s A and AAAA records are correctly set and that port 80 is accessible from the internet for the ACME challenge.

By following these steps, you will have a robust Discourse installation running behind a well-configured Nginx reverse proxy on Debian 12, ready for production use.