Discourse/discourse
Discourse/discourse
0
0
Fork 0
mirror of https://github.com/discourse/discourse.git synced 2026-08-05 18:46:18 +08:00
Code Packages Activity Actions
discourse/docs/INSTALL-cloud.md
Rishabh 48f7fe808a
 DOCS: Mention updated plan names in INSTALL-cloud.md (#41618) 
To match https://discourse.org/pricing. Here's how it'll look:

<img width="1098" height="293" alt="Screenshot 2026-07-10 at 16 11 03"
src="https://github.com/user-attachments/assets/18a782bf-1d9e-425f-8eca-a29e3e892e45"
/>

(t/187320/11)
2026-07-14 16:48:46 +05:30

349 lines
12 KiB
Markdown
Vendored
Raw Permalink Blame History

# 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 plans (Free, Pro, Business or Enterprise) take care of everything for you.
>
> [Learn more about Discourse hosting](https://discourse.org/pricing)
> 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](https://discourse.org/partners).
**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](#quick-start)
- [Requirements](#requirements)
- [Installation](#installation)
- [The Setup Wizard](#the-setup-wizard)
- [After Installation](#after-installation)
- [Advanced Configuration](#advanced-configuration)
- [Troubleshooting](#troubleshooting)
- [Optional Features](#optional-features)
---
## Quick Start
Run this single command on a fresh Ubuntu/Debian server:
```bash
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](https://www.digitalocean.com/?refcode=5fa48ac82415)
- 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](https://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](https://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](https://www.namecheap.com/domains/domain-name-search/)
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:**
```bash
ssh root@your-server-ip
```
---
### Step 3: Run the Installer
```bash
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.
<img src="https://www.discourse.org/images/install/18/discourse-4-wizard-step1.png" width="650">
### Post-Install Security
We strongly recommend enabling automatic security updates:
```bash
# 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:**
```bash
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:
```bash
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](https://www.maxmind.com/en/geolite2/signup) and add it to your `app.yml`:
```yaml
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
```bash
# 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
```bash
# 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:
```bash
# 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](https://meta.discourse.org/t/troubleshooting-email-on-a-new-discourse-install/16326).
---
## Optional Features
After installation, you can enable additional features:
### Authentication
- [Google OAuth2](https://meta.discourse.org/t/configuring-google-oauth2-login-for-discourse/15858)
- [GitHub Login](https://meta.discourse.org/t/configuring-github-login-for-discourse/13745)
- [Facebook Login](https://meta.discourse.org/t/configuring-facebook-login-for-discourse/13394)
- [Twitter/X Login](https://meta.discourse.org/t/configuring-twitter-login-for-discourse/13395)
- [Single Sign-On (SSO)](https://meta.discourse.org/t/official-single-sign-on-for-discourse/13045)
- [More auth plugins on meta.discourse.org](https://meta.discourse.org/tags/c/customization/plugin/22/auth-plugins)
### Email & Notifications
- [Reply via Email](https://meta.discourse.org/t/set-up-reply-via-email-support/14003)
- [Recommended Email Providers](https://github.com/discourse/discourse/blob/main/docs/INSTALL-email.md) — If you skipped SMTP during setup
### Operations
- [Automatic Backups](https://meta.discourse.org/t/configure-automatic-backups-for-discourse/14855)
- [Configure a CDN](https://meta.discourse.org/t/enable-a-cdn-for-your-discourse/14857)
- [Multisite Configuration](https://meta.discourse.org/t/multisite-configuration-with-docker/14084)
- [Webhooks](https://meta.discourse.org/t/setting-up-webhooks/49045)
- [Offline Page During Rebuild](https://meta.discourse.org/t/adding-an-offline-page-when-rebuilding/45238)
### Extending Discourse
- [Install Plugins](https://meta.discourse.org/t/install-a-plugin/19157)
- [Import from Other Platforms](https://meta.discourse.org/t/how-to-migrate-from-one-platform-forum-to-discourse/197236) — vBulletin, phpBB, Vanilla, etc.
- [Embed in WordPress](https://github.com/discourse/wp-discourse)
- [Embed Comments on Static Sites](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963)
---
Help us improve this guide! Feel free to ask questions on [meta.discourse.org](https://meta.discourse.org) or submit a pull request.
> Still finding setup too complex? [Let us host Discourse for you](https://discourse.org/pricing) — we handle everything.
View git blame Copy permalink