Discourse/discourse
Discourse/discourse
0
0
Fork 0
mirror of https://gh.wpcy.net/https://github.com/discourse/discourse.git synced 2026-05-06 16:50:46 +08:00
Code Packages Activity Actions
discourse/docs/INSTALL-cloud.md
Rafael dos Santos Silva 8c49df6303
FEATURE: New install guide for wizard and free domain (#37174) 
This updates our main self-hosting install guide to reflect the new install experience,
including the one-line install script, new wizard and the free subdomain offering via
id.discourse.com


Co-authored-by: Penar Musaraj <pmusaraj@gmail.com>
2026-01-20 14:11:30 -03:00

349 lines
12 KiB
Markdown
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 takes 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/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