Skip to content

Latest commit

 

History

History
349 lines (235 loc) · 11.8 KB

INSTALL-cloud.md

File metadata and controls

349 lines (235 loc) · 11.8 KB

Install Discourse on a Cloud Server

To install and self-host Discourse, follow the steps below. But if you'd rather skip the setup, maintenance, and server management, our official Discourse hosting takes care of everything for you.

Learn more about Discourse hosting

If you prefer to self-host but need help setting it up we have partners who can help. Click here to explore self-hosting set-up options.

Set up Discourse in about 10 minutes with zero knowledge of Rails or Linux shell. Works on any Docker-compatible cloud provider or local server.

Contents

Quick Start

Run this single command on a fresh Ubuntu/Debian server:

wget -qO- https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | sudo bash

That's it! The installer will:

  • Install Docker and git automatically (if not present)
  • Download the Discourse Docker configuration
  • Launch an interactive setup wizard

Don't have a domain name? No problem! The installer offers free subdomains like yoursite.discourse.diy — no purchase required.

Don't want to set up email? Skip SMTP and users can log in via Discourse ID with social logins (Google, Facebook, Apple, GitHub).

Requirements

Server Specifications

Requirement Minimum Recommended
RAM 1 GB (with swap) 2 GB+
CPU 1 core 2+ cores
Disk 10 GB 20 GB+
OS 64-bit Linux Ubuntu LTS

Auto-scaling: The installer automatically tunes UNICORN_WORKERS and db_shared_buffers based on your server's RAM and CPU.

Supported Cloud Providers

The installer works on any cloud provider with Docker support:

  • DigitalOcean
  • AWS EC2
  • Google Cloud Platform
  • Linode / Akamai
  • Vultr
  • Hetzner
  • Any VPS with root SSH access

Installation

Step 1: Choose Your Domain

You have two options:

Option Best For Setup
Free subdomain (mysite.discourse.diy) Testing, learning, hobby projects Claim at id.discourse.com/my/subdomain
Your own domain (forum.example.com) Production, custom branding Purchase from a registrar, configure DNS A record

Free Subdomain

Visit id.discourse.com/my/subdomain anytime to claim your subdomain. You can do this before or during installation:

  1. Log in with your Discourse account (or create one)
  2. Choose your desired subdomain name (e.g., mysite)
  3. When ready to install, click "Generate Code" to get a 6-digit verification code (valid for 10 minutes)

How it works: The installer verifies your code with Discourse ID, then automatically creates a DNS A record pointing yoursite.discourse.diy to your server's IP. No manual DNS configuration required!

Your Own Domain

  1. Purchase a domain from a registrar like Namecheap
  2. Create a DNS A record pointing your subdomain (e.g., forum.example.com) to your server's IP address
  3. Wait for DNS propagation (can take up to 48 hours, usually much faster)

Step 2: Create and Access Your Server

  1. Create a cloud server on any provider (e.g., a DigitalOcean droplet with Ubuntu)

  2. SSH into your server:

    ssh root@your-server-ip

Step 3: Run the Installer

wget -qO- https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | sudo bash

The wizard will guide you through:

  1. Admin email(s) — Enter the email addresses for admin accounts
  2. Domain selection:
    • Select No for free subdomain → enter your subdomain and verification code
    • Select Yes for your own domain → enter your hostname (e.g., forum.example.com)
  3. SMTP configuration — Skip to use Discourse ID login, or configure your email provider

After confirming your settings, the installer builds your Discourse (~5-10 minutes).

Note: SSL certificates via Let's Encrypt are provisioned automatically — no additional configuration required.

The Setup Wizard

SMTP is Optional

Unlike previous versions, you can skip email configuration during initial setup. When you skip SMTP, the installer automatically enables Login via Discourse ID, which provides:

  • Email-based login — Users sign in through id.discourse.com (no SMTP needed)
  • Social logins — Google, Facebook, Apple, and GitHub authentication built-in
  • Centralized identity — Users can use the same account across multiple Discourse communities
  • Web push notifications — Users still receive real-time notifications on all browsers and PWA-enabled devices

This is perfect for:

  • Getting started quickly without email provider setup
  • Communities that prefer social login over email registration
  • Mobile-first communities using the PWA experience

Note: If you want traditional email features (email digests, mailing list mode, or email replies), you can configure SMTP later via Admin → Email or by re-running the setup wizard.

Automatic Features

The wizard handles these automatically:

  • Public IP detection — Finds your server's IP using multiple services
  • Resource scaling — Sets optimal UNICORN_WORKERS and db_shared_buffers based on your hardware
  • Port validation — Checks that ports 80 and 443 are available
  • DNS verification — Confirms your domain resolves to this server
  • Swap creation — Offers to create swap space on low-memory servers

After Installation

Access Your Forum

Once the build completes (5-10 minutes), your forum will be available at:

  • https://yoursite.discourse.diy (free subdomain)
  • https://forum.example.com (your own domain)

Register Your Admin Account

  1. Visit your forum URL
  2. Click Sign Up or Log In
  3. If using Discourse ID login: sign in with Google, Facebook, Apple, GitHub, or email via id.discourse.com
  4. If using SMTP: use one of the admin emails you entered during setup and check your inbox
  5. Complete the in-app setup wizard that appears after registration

Tip: Make sure you register with one of the admin emails you entered during installation to get admin privileges.

Post-Install Security

We strongly recommend enabling automatic security updates:

# Ubuntu/Debian - enable unattended upgrades
dpkg-reconfigure -plow unattended-upgrades

# Install fail2ban for brute-force protection
apt install fail2ban

Upgrading Discourse

Via web UI (recommended): Visit https://your-forum/admin/upgrade and click Upgrade

Via command line:

cd /var/discourse
./launcher rebuild app

Discourse will email you when new versions are available. Stay current for the latest features and security fixes.

Advanced Configuration

Manual Configuration

For advanced users, edit the configuration file directly:

nano /var/discourse/containers/app.yml
cd /var/discourse
./launcher rebuild app

MaxMind Geolocation

For IP-based geolocation features (country detection, etc.), register for a free MaxMind GeoLite2 license key and add it to your app.yml:

env:
  DISCOURSE_MAXMIND_LICENSE_KEY: "your_license_key_here"

Launcher Commands

The launcher script in /var/discourse provides these commands:

Usage: launcher COMMAND CONFIG [--skip-prereqs] [--docker-args STRING]
Commands:
    start       Start/initialize a container
    stop        Stop a running container
    restart     Restart a container
    destroy     Stop and remove a container
    enter       Open a shell inside the container
    logs        View Docker logs for a container
    bootstrap   Bootstrap a container from template
    rebuild     Rebuild a container (destroy old, bootstrap, start new)
    cleanup     Remove stopped containers (> 24 hours old)

Troubleshooting

Ports 80/443 Already in Use

# Check what's using the ports
lsof -i :80
lsof -i :443

# Stop conflicting services
systemctl stop nginx    # or apache2
systemctl disable nginx

DNS Verification Fails

  • Ensure your A record points to the correct server IP
  • DNS propagation can take up to 48 hours
  • Use --skip-connection-test to bypass verification temporarily

Free Subdomain Issues

  • Ensure you're using the same Discourse ID account that claimed the subdomain
  • Verification codes expire after 10 minutes — generate a new one if expired
  • Each subdomain can only be claimed by one user

Build or Bootstrap Errors

# View container logs
cd /var/discourse
./launcher logs app

# Enter container for debugging
./launcher enter app

# Check Rails production logs
cat /var/discourse/shared/standalone/log/rails/production.log

Low Memory Errors

The installer will offer to create swap space. You can also create it manually:

# Create 2GB swap
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile swap swap defaults 0 0' >> /etc/fstab

Email Not Working

If you configured SMTP but emails aren't sending, see the Email Troubleshooting Guide.

Optional Features

After installation, you can enable additional features:

Authentication

Email & Notifications

Operations

Extending Discourse

Help us improve this guide! Feel free to ask questions on meta.discourse.org or submit a pull request.

Still finding setup too complex? Let us host Discourse for you — we handle everything.