### Initial Setup Workflow

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Commands for the initial setup and starting of a Discourse instance.

```bash
./launcher bootstrap standalone
./launcher start standalone
```

--------------------------------

### Launcher Script Usage Examples

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Examples demonstrating common commands for the `launcher` script, including bootstrapping, starting, entering a container, viewing logs, and rebuilding.

```bash
./launcher bootstrap app              # Build
./launcher start app                  # Start
./launcher enter app                  # Shell access
./launcher logs app | tail -50        # View logs
./launcher rebuild app                # Update
```

--------------------------------

### Example Usage with Configuration File

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Example of starting a Discourse instance using a specific configuration file.

```bash
# Using config file: containers/standalone.yml
./launcher start standalone
```

--------------------------------

### Hooks Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of defining custom installation steps using pups syntax for various hook types.

```yaml
hooks:
  before_code:
    - replace:
        filename: /some/file
        from: "old content"
        to: "new content"
  after_code:
    - exec:
        cd: /tmp
        cmd:
          - git clone https://github.com/user/plugin.git
  code:
    - exec: echo "Running during code setup"
```

--------------------------------

### Installation (One-liner)

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Quick installation command that automates Docker setup, discourse_docker configuration, and Discourse bootstrapping.

```bash
curl https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | bash
```

--------------------------------

### Manual Installation Steps

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Steps for manually installing Discourse Docker, including installing Docker, cloning the repository, and running the setup wizard or bootstrapping manually.

```bash
# SSH to Ubuntu 20.04+ server
ssh root@example.com

# Install Docker
curl -fsSL https://get.docker.com | bash

# Clone discourse_docker
git clone https://github.com/discourse/discourse_docker.git
cd discourse_docker

# Run setup wizard
sudo ./discourse-setup

# Or manually create config
sudo ./launcher bootstrap app
sudo ./launcher start app
```

--------------------------------

### Run Image Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of specifying the Docker image to use when starting the container.

```yaml
run_image: local_discourse/standalone
```

--------------------------------

### Install Discourse - Execution Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Commands to download and run the install-discourse script.

```bash
# Download and run
curl https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | bash

# Or if already in /var/discourse
sudo ./install-discourse
```

--------------------------------

### Docker Args Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of providing additional Docker arguments for container startup.

```yaml
docker_args: "--cpus=2 --memory=2g"
```

--------------------------------

### Multi-Container (Web-Only) Bootstrap and Start Commands

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Bash commands to bootstrap and start individual containers in a multi-container setup.

```bash
# Database container
./launcher bootstrap db
./launcher start db

# Redis container
./launcher bootstrap redis
./launcher start redis

# Web container (points to db and redis)
./launcher bootstrap web
./launcher start web
```

--------------------------------

### Run Commands Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of commands executed after bootstrap completes using pups syntax.

```yaml
run:
  - exec: echo "Beginning of custom commands"
  - exec:
      cd: /var/www/discourse
      cmd:
        - bundle exec rake assets:precompile
  - file:
      path: /etc/cron.d/my-cron
      contents: |
        * * * * * root /usr/bin/my-command
```

--------------------------------

### Standalone Configuration Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

A sample configuration file for a standalone Discourse Docker setup.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/web.ssl.template.yml"
  - "templates/web.letsencrypt.ssl.template.yml"

expose:
  - "80:80"
  - "443:443"

env:
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: admin@example.com
  DISCOURSE_SMTP_ADDRESS: smtp.gmail.com
  DISCOURSE_SMTP_PORT: 587
  DISCOURSE_SMTP_USER_NAME: noreply@example.com
  DISCOURSE_SMTP_PASSWORD: "password"
  DISCOURSE_SMTP_FORCE_TLS: true

volumes:
  - volume:
      host: /var/discourse/shared/standalone
      guest: /shared
  - volume:
      host: /var/discourse/shared/standalone/log/var-log
      guest: /var/log

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/docker_manager.git
```

--------------------------------

### expose example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of various port mapping and exposure formats.

```yaml
expose:
  - "80:80"        # HTTP to all interfaces
  - "443:443"      # HTTPS to all interfaces
  - "127.0.0.1:20080:80"  # Debug access on localhost only
  - "2222:22"      # SSH on different port
  - "8080"         # Expose 8080 internally
```

--------------------------------

### Install Docker

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Command to install Docker if it is not already installed.

```bash
curl -fsSL https://get.docker.com -o get-docker.sh && sh get-docker.sh
```

--------------------------------

### Boot Command Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of overriding the container boot command.

```yaml
boot_command: /sbin/boot
```

--------------------------------

### Fresh Installation Workflow

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Steps to perform a fresh Discourse installation using the provided script.

```bash
# 1. SSH to server (Ubuntu 20.04+)
ssh root@server.example.com

# 2. Run installer
curl https://raw.githubusercontent.com/discourse/discourse_docker/main/install-discourse | bash

# 3. Complete setup wizard prompts
# - Domain: discourse.example.com
# - Email settings
# - SSL setup

# 4. Access at https://discourse.example.com
```

--------------------------------

### Configuration Hierarchy Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

An example demonstrating how settings are applied in order of priority, with overrides.

```yaml
# templates/postgres.template.yml sets:
db_shared_buffers: 256MB

# templates/web.template.yml sets:
UNICORN_WORKERS: 3

# containers/app.yml overrides:
env:
  UNICORN_WORKERS: 4  # Now 4, not 3

# Launcher flag overrides all:
./launcher start app --docker-args "--cpus=2"
```

--------------------------------

### discourse-setup Configuration Output Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Example of the containers/app.yml file generated by discourse-setup, showing templates, exposed ports, and environment variables.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/web.ssl.template.yml"
  - "templates/web.letsencrypt.ssl.template.yml"
  # ... other templates as selected

expose:
  - "80:80"
  - "443:443"

env:
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: admin@example.com
  DISCOURSE_SMTP_ADDRESS: smtp.example.com
  DISCOURSE_SMTP_PORT: 587
  # ... other settings
```

--------------------------------

### Labels Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Another example of Docker container labels.

```yaml
labels:
  app: discourse
  environment: production
  team: platform
```

--------------------------------

### start command

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Starts a previously bootstrapped container, or initializes it for the first time.

```bash
./launcher start CONFIG [--skip-prereqs] [--docker-args STRING]
```

```bash
./launcher start standalone
./launcher start app --docker-args "--cpus=2 --memory=2g"
```

--------------------------------

### No Boot Command Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of disabling the automatic boot command.

```yaml
no_boot_command: true
```

--------------------------------

### templates example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of including multiple template YAML files.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/web.ssl.template.yml"
```

--------------------------------

### Example Usage of image-base-build

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Examples demonstrating how to use the image-base-build script with different options.

```bash
./bin/image-base-build --tag discourse/base:custom

# Build without cache
./bin/image-base-build --no-cache

# Build with custom base image
./bin/image-base-build --build-arg BASE=ubuntu:22.04
```

--------------------------------

### Volume Mounts Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Another example of Docker volume mounts.

```yaml
volumes:
  - volume:
      host: /var/discourse/shared/app
      guest: /shared
  - volume:
      host: /var/discourse/shared/app/log/var-log
      guest: /var/log
```

--------------------------------

### Base Image Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of overriding the base Docker image.

```yaml
base_image: discourse/base:2.0.20260521-0047
```

--------------------------------

### Web-Only Configuration (Multi-Container)

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example YAML configuration for a multi-container web-only Discourse setup.

```yaml
templates:
  - "templates/web.template.yml"
  - "templates/web.ratelimited.template.yml"

expose:
  - "80:80"
  - "443:443"

env:
  RAILS_ENV: production
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DB_HOST: db-container
  DISCOURSE_DB_PORT: 5432
  # ... other settings

links:
  - link:
      name: db-container
      alias: postgres
  - link:
      name: redis-container
      alias: redis

volumes:
  - volume:
      host: /var/discourse/shared/web
      guest: /shared
```

--------------------------------

### Update Pups Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of controlling whether to update pups on bootstrap.

```yaml
update_pups: false
```

--------------------------------

### Troubleshooting Existing Installation Workflow

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Commands for diagnosing and managing an existing Discourse installation.

```bash
cd /var/discourse

# 1. Run diagnostics
sudo ./discourse-doctor

# 2. Check logs
./launcher logs app

# 3. Enter container
./launcher enter app

# 4. Rebuild if needed
./launcher rebuild app
```

--------------------------------

### Hooks Example

Source: https://github.com/discourse/discourse_docker/blob/main/README.md

Example of defining a hook to run code before or after certain logic.

```yaml
hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://github.com/discourse/docker_manager
```

--------------------------------

### web.letsencrypt.ssl.template.yml Example Configuration

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/templates.md

Example configuration for enabling automatic SSL certificate management via Let's Encrypt.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/web.ssl.template.yml"
  - "templates/web.letsencrypt.ssl.template.yml"

expose:
  - "80:80"
  - "443:443"

env:
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: admin@example.com
```

--------------------------------

### Troubleshooting: Root Permissions

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Command to run the install script with root privileges.

```bash
sudo ./install-discourse
```

--------------------------------

### discourse-setup Execution

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Example of how to navigate to the discourse_docker directory and execute the discourse-setup script.

```bash
cd /var/discourse
sudo ./discourse-setup
```

--------------------------------

### Hook Syntax Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Demonstrates the pups syntax for defining hooks, including exec, replace, and file operations.

```yaml
hooks:
  after_code:
    - exec:
        cd: /path/to/run/from
        cmd:
          - bash -c "command here"
          - echo "multiple commands"
    - replace:
        filename: /path/to/file
        from: "pattern to find"
        to: "replacement text"
    - file:
        path: /path/to/file
        chmod: "+x"
        contents: |
          #!/bin/bash
          echo "file contents"
```

--------------------------------

### Development Setup

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

A configuration suitable for local development of Discourse.

```yaml
env:
  RAILS_ENV: development
  DISCOURSE_HOSTNAME: localhost
  DISCOURSE_DEVELOPER_EMAILS: dev@localhost
  DISCOURSE_SKIP_EMAIL_SETUP: 1
  
  PRECOMPILE_ON_BOOT: 0
  RAILS_LOG_LEVEL: debug
```

--------------------------------

### Development vs Production: Development Configuration

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Example YAML configuration for development environment settings.

```yaml
env:
  RAILS_ENV: development
  DISCOURSE_HOSTNAME: localhost
  PRECOMPILE_ON_BOOT: 0
  RAILS_LOG_LEVEL: debug
```

--------------------------------

### Labels Example

Source: https://github.com/discourse/discourse_docker/blob/main/README.md

Example of adding labels to a Discourse Docker container.

```yaml
labels:
  monitor: 'true'
  app_name: '{{config}}_discourse'
```

--------------------------------

### Development vs Production: Production Configuration

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Example YAML configuration for production environment settings.

```yaml
env:
  RAILS_ENV: production
  DISCOURSE_HOSTNAME: discourse.example.com
  PRECOMPILE_ON_BOOT: 1
  RAILS_LOG_LEVEL: info
  DISCOURSE_FORCE_HTTPS: true
```

--------------------------------

### Proxy Configuration Example

Source: https://github.com/discourse/discourse_docker/blob/main/README.md

Example of adding proxy information to the container environment for networks with no direct internet access.

```yaml
env:
  …existing entries…
  HTTP_PROXY: http://proxyserver:port/
  http_proxy: http://proxyserver:port/
  HTTPS_PROXY: http://proxyserver:port/
  https_proxy: http://proxyserver:port/
```

--------------------------------

### Minimal Production Setup

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

A minimal configuration for a production Discourse instance.

```yaml
env:
  RAILS_ENV: production
  LANG: en_US.UTF-8
  LC_ALL: en_US.UTF-8
  LANGUAGE: en_US.UTF-8

  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: admin@example.com
  
  DISCOURSE_SMTP_ADDRESS: smtp.gmail.com
  DISCOURSE_SMTP_PORT: 587
  DISCOURSE_SMTP_USER_NAME: noreply@example.com
  DISCOURSE_SMTP_PASSWORD: "password"
  DISCOURSE_SMTP_FORCE_TLS: true
  
  UNICORN_WORKERS: 4
  UNICORN_SIDEKIQS: 2
```

--------------------------------

### Docker Labels

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of Docker container labels for metadata.

```yaml
labels:
  com.example.version: "1.0"
  com.example.description: "Discourse Forum"
```

--------------------------------

### Template Inheritance Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/templates.md

Demonstrates how to use template inheritance for configuration overrides, specifically for PostgreSQL versions.

```yaml
templates:
  - "templates/postgres.template.yml"    # Base postgres config
  - "templates/postgres.15.template.yml" # Override with v15
```

--------------------------------

### Docker Links (Legacy)

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of Docker container links (legacy, prefer networking).

```yaml
links:
  - link:
      name: postgres
      alias: postgres
```

--------------------------------

### Template Merging Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Demonstrates how templates are merged in order, with later templates overriding earlier ones.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/postgres.15.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/web.ssl.template.yml"
```

--------------------------------

### Performance Optimization: Configuration Tuning

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Example YAML configuration for tuning database shared buffers, Unicorn workers, and Sidekiq workers.

```yaml
params:
  db_shared_buffers: "2GB"      # 25% of RAM
  
env:
  UNICORN_WORKERS: 8            # 1 per CPU core
  UNICORN_SIDEKIQS: 3           # 1-3 depending on load
  RUBY_GC_HEAP_GROWTH_MAX_SLOTS: 40000
```

--------------------------------

### Environment Variables

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of environment variables for the Discourse container.

```yaml
env:
  RAILS_ENV: 'production'
  LANG: en_US.UTF-8
  LANGUAGE: en_US.UTF-8
  LC_ALL: en_US.UTF-8
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: me@example.com,you@example.com
  DISCOURSE_SMTP_ADDRESS: smtp.example.com
  DISCOURSE_SMTP_PORT: 587
  DISCOURSE_SMTP_USER_NAME: user@example.com
  DISCOURSE_SMTP_PASSWORD: "pa$$word"
  DISCOURSE_SMTP_FORCE_TLS: false
  DISCOURSE_SMTP_DOMAIN: discourse.example.com
  DISCOURSE_SMTP_AUTHENTICATION: plain
```

--------------------------------

### Development Configuration

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example YAML configuration for a Discourse development environment.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"

env:
  RAILS_ENV: development
  DISCOURSE_HOSTNAME: localhost
  DISCOURSE_SKIP_EMAIL_SETUP: "1"
  PRECOMPILE_ON_BOOT: "0"

expose:
  - "3000:3000"
  - "9203:9203"

volumes:
  - volume:
      host: /home/user/discourse
      guest: /var/www/discourse
  - volume:
      host: /var/discourse/shared/dev
      guest: /shared
```

--------------------------------

### Setup DISCOURSE_CDN_URL

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

Steps to configure DISCOURSE_CDN_URL, rebuild the app, and rebake posts.

```bash
./launcher rebuild app
./launcher run app "cd /var/www/discourse && RAILS_ENV=production rake posts:rebake"
```

--------------------------------

### Volume Mounts

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Example of Docker volume mounts for persistent data.

```yaml
volumes:
  - volume:
      host: /var/discourse/shared/standalone
      guest: /shared
  - volume:
      host: /var/discourse/shared/standalone/log/var-log
      guest: /var/log
```

--------------------------------

### Using Custom Templates

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/templates.md

Example YAML showing how to include a custom template in the Discourse configuration.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/custom.template.yml"
```

--------------------------------

### High Performance Setup

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

A configuration optimized for high performance in a Discourse production environment.

```yaml
env:
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: admin@example.com
  
  DISCOURSE_SMTP_ADDRESS: smtp.example.com
  DISCOURSE_SMTP_PORT: 587
  DISCOURSE_SMTP_USER_NAME: mail@example.com
  DISCOURSE_SMTP_PASSWORD: "password"
  
  DISCOURSE_CDN_URL: https://cdn.example.com
  
  UNICORN_WORKERS: 8
  UNICORN_SIDEKIQS: 3
  
  PRECOMPILE_ON_BOOT: 1
  
  RAILS_LOG_LEVEL: info
```

--------------------------------

### Skip Prerequisite Validation

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Skips all prerequisite validation checks when starting a container.

```bash
./launcher start app --skip-prereqs
```

--------------------------------

### Container Hostname Configuration

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Example YAML configuration for setting container hostname and Discourse hostname.

```yaml
env:
  DOCKER_USE_HOSTNAME: true
  DISCOURSE_HOSTNAME: discourse.example.com
```

--------------------------------

### Upgrade Discourse Workflow

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Steps to back up and upgrade an existing Discourse installation.

```bash
cd /var/discourse

# 1. Back up data
./launcher run app tar czf /shared/backups/pre-upgrade.tar.gz /shared
```

--------------------------------

### Example of setting upload_size in params

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

Demonstrates how to set the UPLOAD_SIZE environment variable within the params section of a configuration file.

```yaml
params:
  upload_size: 50m
```

--------------------------------

### Skip prerequisite checks

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Set SKIP_PREREQS to any value to skip prerequisite checks before starting the application.

```bash
export SKIP_PREREQS=1
./launcher start app
```

--------------------------------

### Manual Performance Tuning Configuration

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Example of manually overriding performance tuning parameters in app.yml.

```yaml
env:
  UNICORN_WORKERS: 8

params:
  db_shared_buffers: "2GB"
```

--------------------------------

### Environment Variables Example

Source: https://github.com/discourse/discourse_docker/blob/main/README.md

Example of setting environment variables for a Discourse Docker container.

```yaml
env:
  DISCOURSE_DB_HOST: some-host
  DISCOURSE_DB_NAME: '{{config}}_discourse'
```

--------------------------------

### Unicorn Workers Configuration Example

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

Example of setting the UNICORN_WORKERS environment variable in a YAML configuration.

```yaml
env:
  UNICORN_WORKERS: 4
```

--------------------------------

### Discourse Doctor - Example Output

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

An example of the output generated by the discourse-doctor script, showing diagnostic results for Docker, memory, disk space, and connectivity.

```text
==================== DOCKER INFO ====================
DOCKER VERSION: Docker version 24.0.7

DOCKER PROCESSES (docker ps -a):
CONTAINER ID   IMAGE                    STATUS
abc123def456   local_discourse/app      Up 2 hours
...

==================== MEMORY INFORMATION ====================
RAM: 8192 MB
Memory  (% used): 4096 MB (50%)

==================== DISK SPACE CHECK ====================
Filesystem     Size  Used Avail Use%
/              100G   45G   50G  45%
/var/discourse  50G   15G   35G  30%
...

==================== CONNECTIVITY CHECK ====================
Checking domain resolution...
Connection to discourse.example.com:443 succeeded.
```

--------------------------------

### Performance Optimization: Monitoring

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Commands to monitor resource usage, process count, and database size.

```bash
# Watch resource usage
docker stats

# Check process count
./launcher enter app
ps aux | wc -l

# Monitor database size
./launcher run app "du -sh /shared/postgres_data"
```

--------------------------------

### bootstrap command

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Initializes and builds a new Docker container based on a configuration template.

```bash
./launcher bootstrap CONFIG [--skip-prereqs] [--docker-args STRING]
```

```bash
./launcher bootstrap standalone
./launcher bootstrap app --skip-prereqs
```

--------------------------------

### restart command

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Restarts a running container by stopping and starting it.

```bash
./launcher restart CONFIG [--skip-prereqs] [--docker-args STRING]
```

```bash
./launcher restart standalone
```

--------------------------------

### Multi-Container (Web Only)

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/environment-variables.md

A configuration for a multi-container setup focusing on the web component only.

```yaml
env:
  DISCOURSE_HOSTNAME: discourse.example.com
  DISCOURSE_DEVELOPER_EMAILS: admin@example.com
  
  DISCOURSE_DB_HOST: postgres-container
  DISCOURSE_DB_PORT: 5432
  
  UNICORN_WORKERS: 4
  UNICORN_SIDEKIQS: 2
```

--------------------------------

### Running Commands - Database Migrations

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Command to run database migrations within a Discourse container.

```bash
./launcher run standalone "cd /var/www/discourse && RAILS_ENV=production rake db:migrate"
```

--------------------------------

### Run Discourse Diagnostics

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Runs diagnostic checks for Discourse installation issues.

```bash
./discourse-doctor
```

--------------------------------

### Create Manual Backup

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Creates a manual backup of the Discourse application data.

```bash
./launcher run app tar czf /shared/backups/manual-$(date +%s).tar.gz /shared
```

--------------------------------

### Troubleshooting Workflow: Commands

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

A step-by-step workflow for troubleshooting Discourse issues, including commands for checking status, viewing logs, running diagnostics, and entering the container.

```bash
1. **Check status** - `docker ps -a`
2. **View logs** - `./launcher logs app | tail -100`
3. **Run diagnostics** - `./discourse-doctor`
4. **Enter container** - `./launcher enter app`
5. **Check services** - `sv status *` in container
6. **Check disk** - `df -h`
7. **Check memory** - `free -m`
8. **Check network** - `ping external-host`
9. **Rebuild if needed** - `./launcher rebuild app`
```

--------------------------------

### High Performance Templates

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/templates.md

Example YAML configuration for optimizing Discourse for throughput and latency.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/enable-ruby-yjit.yml"
  - "templates/cache-dns.template.yml"
```

--------------------------------

### CDN Accelerated Templates

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/templates.md

Example YAML configuration for enabling CDN acceleration with Cloudflare.

```yaml
templates:
  - "templates/postgres.template.yml"
  - "templates/redis.template.yml"
  - "templates/web.template.yml"
  - "templates/cloudflare.template.yml"
```

--------------------------------

### discourse-doctor Execution

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Example of how to execute the discourse-doctor script, both generally and for a specific container.

```bash
cd /var/discourse
sudo ./discourse-doctor
# or with specific container
sudo ./discourse-doctor app
```

--------------------------------

### expose

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/configuration.md

Docker port mappings and exposures.

```yaml
expose:
  - "80:80"           # container_port:host_port
  - "443:443"
  - "127.0.0.1:20080:80"  # interface:host_port:container_port
```

--------------------------------

### Debugging Workflow - Inspect Startup Command

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Command to inspect the startup command of a Discourse container.

```bash
./launcher start-cmd standalone
```

--------------------------------

### Running Commands - Precompile Assets

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/launcher-cli.md

Command to precompile assets within a Discourse container.

```bash
./launcher run standalone "cd /var/www/discourse && RAILS_ENV=production rake assets:precompile"
```

--------------------------------

### PostgreSQL Version-Specific Template Usage

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/templates.md

Example of how to specify a particular PostgreSQL version using its template.

```yaml
templates:
  - "templates/postgres.15.template.yml"  # Use PostgreSQL 15
```

--------------------------------

### Default Port Mapping

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/system-overview.md

Default port mapping between the host and container for a standalone setup.

```text
Host Port  →  Container Port  →  Service
80         →  80             →  Nginx (HTTP)
443        →  443            →  Nginx (HTTPS)
```

--------------------------------

### View Application Logs

Source: https://github.com/discourse/discourse_docker/blob/main/_autodocs/helper-scripts.md

Commands to view Discourse application logs, including tailing and following.

```bash
./launcher logs app              # Last 20 lines
./launcher logs app | tail -100  # Last 100 lines
./launcher logs app --follow     # Stream in real-time
```