Install and Configure Outline Wiki on

Configuration

After installing the components, you need to configure a web server to proxy requests to Outline and provide HTTPS. We will use Caddy — a modern web server that automatically manages Let's Encrypt certificates.

1. Installing Caddy (version 2.7.x as of 2026)

Caddy can be installed from the official repository. First, add the GPG key:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list

Then update the package list and install Caddy:

sudo apt update
sudo apt install caddy -y

Verify that Caddy is installed and running:

sudo systemctl status caddy

It should be active (active (running)).

2. Configuring the Caddyfile

Caddy uses a configuration file called Caddyfile. We will configure it to act as a reverse proxy for Outline Wiki and automatically obtain HTTPS certificates.

sudo nano /etc/caddy/Caddyfile

Remove all file content and paste the following, replacing YOUR_DOMAIN.COM with your actual domain:

YOUR_DOMAIN.COM {
  # Enable automatic HTTPS certificates from Let's Encrypt
  tls {
    dns cloudflare ВАШ_КЛЮЧ_API_CLOUDFLARE
    # If you are not using Cloudflare DNS, simply use "tls [email protected]"
    # Caddy will use the HTTP-01 challenge, which requires port 80 to be open.
    # If port 80 is occupied, or you are behind NAT, the DNS challenge is preferred.
  }

  # Proxy requests to the Outline Docker container
  reverse_proxy localhost:3000 {
    # Additional headers required for Outline
    header_up Host {host}
    header_up X-Real-IP {remote_ip}
    header_up X-Forwarded-For {remote_ip}
    header_up X-Forwarded-Proto {scheme}
  }

  # Optional: compression for faster loading
  encode gzip zstd

  # Optional: logging
  log {
    output file /var/log/caddy/outline.log
  }
}

Important:

• DNS provider: If your domain is managed through Cloudflare (or another DNS provider supported by Caddy), you can use the DNS challenge to obtain certificates. This is convenient if you have a complex network configuration or port 80 is unavailable. Replace ВАШ_КЛЮЧ_API_CLOUDFLARE with your Cloudflare API token. You will also need to install the Caddy plugin for Cloudflare if it's not enabled by default (sudo apt install caddy-dns-cloudflare).
• HTTP-01 challenge: If you are not using the DNS challenge, simply specify tls [email protected] (replace with your email). Caddy will attempt to obtain a certificate via the HTTP-01 challenge, which requires port 80 to be open and accessible from outside.
• Logging: Create a directory for logs: sudo mkdir -p /var/log/caddy && sudo chown caddy:caddy /var/log/caddy.

Save changes (Ctrl+O, Enter) and exit (Ctrl+X).

3. Verify and Reload Caddy

Check the Caddyfile syntax:

sudo caddy validate --config /etc/caddy/Caddyfile

If there are no errors, reload Caddy to apply the new configuration:

sudo systemctl reload caddy

Caddy will automatically obtain and install an SSL certificate for your domain. This may take a few seconds.

4. DNS Configuration

Ensure that your domain (YOUR_DOMAIN.COM) points to your VPS's IP address. Create an A-record with your DNS provider, for example:

Type: A
Name: @ (or your subdomain, e.g., wiki)
Value: ВАШ_IP_АДРЕС_VPS

DNS record propagation may take some time (from a few minutes to several hours).

5. Verifying Functionality

Once DNS updates, open your domain (https://YOUR_DOMAIN.COM) in your browser. You should see the Outline Wiki welcome page. Register the first user (they will become the administrator).

You can also check accessibility from the server:

curl -I https://YOUR_DOMAIN.COM # Check HTTP headers

You should see an HTTP/2 200 status and headers indicating a successful response.

If problems arise, check Caddy logs:

sudo journalctl -u caddy -f

And Outline container logs:

docker compose logs -f outline

At this point, Outline Wiki is fully configured, accessible via HTTPS, and ready for use.

Backups and Maintenance

Regular backups are a critically important part of operating any service. For Outline Wiki, it is necessary to back up the database, uploaded files, and configuration files.

1. What to Back Up

• PostgreSQL Database: Contains all text information, wiki structure, users, and their permissions. This is the most important component.
• Uploaded Files: The directory ./data/uploads contains images, documents, and other files attached to wiki pages.
• Configuration Files: The docker-compose.yml and .env files. Although they can be recreated, saving the current versions will simplify recovery.

2. Simple Auto-Backup Script

Let's create a simple script that will perform a backup and save it to a separate directory. Navigate to the Outline root directory (~/outline).

mkdir -p ~/outline/backups
nano ~/outline/backup_outline.sh

Insert the following content:

#!/bin/bash

# Backup directory
BACKUP_DIR="/home/outlineadmin/outline/backups"
TIMESTAMP=$(date +"%Y%m%d%H%M%S")
DB_BACKUP_FILE="$BACKUP_DIR/outline_db_backup_$TIMESTAMP.sql.gz"
UPLOADS_BACKUP_FILE="$BACKUP_DIR/outline_uploads_backup_$TIMESTAMP.tar.gz"
CONFIG_BACKUP_FILE="$BACKUP_DIR/outline_config_backup_$TIMESTAMP.tar.gz"

# Change to Outline directory for correct docker compose operation
cd /home/outlineadmin/outline || { echo "Failed to change directory to ~/outline"; exit 1; }

echo "Starting Outline Wiki backup at $TIMESTAMP..."

# 1. PostgreSQL Database Backup
echo "Backing up PostgreSQL database..."
# Using docker exec to run pg_dump inside the postgres container
# Get postgres container name from docker-compose.yml
POSTGRES_CONTAINER=$(docker compose ps -q postgres)
if [ -z "$POSTGRES_CONTAINER" ]; then
    echo "Error: PostgreSQL container not found."
    exit 1
fi

# Get environment variables from .env
source ./.env

docker exec "$POSTGRES_CONTAINER" pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" | gzip > "$DB_BACKUP_FILE"
if [ $? -eq 0 ]; then
    echo "PostgreSQL database backup created: $DB_BACKUP_FILE"
else
    echo "Error backing up PostgreSQL database."
    exit 1
fi

# 2. Uploaded Files Backup
echo "Backing up uploaded files..."
tar -czf "$UPLOADS_BACKUP_FILE" ./data/uploads
if [ $? -eq 0 ]; then
    echo "Uploaded files backup created: $UPLOADS_BACKUP_FILE"
else
    echo "Error backing up uploaded files."
    exit 1
fi

# 3. Configuration Files Backup
echo "Backing up configuration files..."
tar -czf "$CONFIG_BACKUP_FILE" ./.env ./docker-compose.yml
if [ $? -eq 0 ]; then
    echo "Configuration files backup created: $CONFIG_BACKUP_FILE"
else
    echo "Error backing up configuration files."
    exit 1
fi

# 4. Deleting old backups (keep last 7 days)
echo "Cleaning up old backups..."
find "$BACKUP_DIR" -type f -name "outline_*.gz" -mtime +7 -delete
echo "Old backups cleaned up."

echo "Outline Wiki backup completed."

Save the file and make it executable:

chmod +x ~/outline/backup_outline.sh

Test the script by running it manually:

~/outline/backup_outline.sh
ls ~/outline/backups/

You should see the created backup files.

3. Automating Backups with Cron

Add the script to the Cron scheduler for daily execution. For example, every day at 3:00 AM:

crontab -e

Add the following line to the end of the file (make sure the script path is correct):

0 3 * * * /home/outlineadmin/outline/backup_outline.sh >> /var/log/outline_backup.log 2>&1

This line will run the script every day at 3 AM and write the output to the log file /var/log/outline_backup.log.

4. Where to Store Backups

Storing backups on the same server as the main service is extremely risky. If the server fails, you will lose both your data and your backups. It is recommended to use:

• External S3-compatible storage: AWS S3, DigitalOcean Spaces, Backblaze B2. This is a reliable and relatively inexpensive storage method. You can configure the script to automatically upload backups to S3.
• Separate VPS: A small, inexpensive VPS dedicated solely to storing backups, to which files can be copied via rsync/scp.
• Local NAS/server: If you have your own hardware.

For automatic upload to S3, you can use s3cmd or aws cli. Example of adding to the script after creating backups:

# Install aws cli (if not installed)
# sudo apt install awscli -y
# aws configure # Configure your AWS keys

# ... (after creating backups) ...

echo "Uploading backups to S3..."
aws s3 cp "$DB_BACKUP_FILE" s3://your-s3-bucket/outline/db/
aws s3 cp "$UPLOADS_BACKUP_FILE" s3://your-s3-bucket/outline/uploads/
aws s3 cp "$CONFIG_BACKUP_FILE" s3://your-s3-bucket/outline/config/
echo "Backups uploaded to S3."

5. Updates: rolling vs maintenance window

Updating Outline Wiki and its components (PostgreSQL, Redis, Docker) requires careful attention.

• Updating Outline Wiki: The simplest way is to update the Docker image. Navigate to the ~/outline directory and execute:

  
              docker compose pull outline # Download new Outline image
              docker compose up -d outline # Recreate Outline container with the new image
              

  Always read the Outline changelog before updating to learn about possible changes in requirements or DB migrations.

• Updating System Packages (Ubuntu): Regularly run sudo apt update && sudo apt upgrade -y. This can be done weekly or monthly.
• Updating Docker Engine: Do this less frequently and with caution, as it can affect all containers. It is recommended to do this within a "maintenance window".

Update Strategy:

• Rolling updates (for Outline): If there are no critical database changes, updating the Outline image can be considered "rolling" (without downtime).
• Maintenance window (for Docker, OS, major Outline updates): For larger updates that could potentially disrupt service operation, allocate a maintenance window, warn users, and perform the update with a fresh backup at hand.

Troubleshooting + FAQ

In this section, we will cover typical problems you might encounter when installing and configuring Outline Wiki, and answer frequently asked questions.

Cannot connect to Outline Wiki by domain name. What to check?

First, ensure that the DNS record for your domain (A-record) correctly points to your VPS's IP address. You can check this with the command dig YOUR_DOMAIN.COM on your local machine. Then, check if Caddy is running: sudo systemctl status caddy. If Caddy is not running or has errors, check its logs: sudo journalctl -u caddy -f. Make sure ports 80 and 443 are open in UFW: sudo ufw status. Also, check that the Outline Docker container is running: docker compose ps.

Outline Wiki returns a 502 Bad Gateway error. What is the cause?

A 502 error usually means that Caddy could not connect to the backend service (Outline). This can be caused by the Outline container not running, or it is running but not listening on the expected port (3000). Check the status of the Outline container: docker compose ps. If it is not running, check the container logs: docker compose logs outline. Make sure that in the .env and docker-compose.yml files, the Outline port is set to 3000 and Caddy proxies requests specifically to localhost:3000.

What is the minimum VPS configuration suitable for Outline Wiki?

For a small number of users (up to 5-10 active), the minimum configuration is 1 vCPU, 2 GB RAM, and 20-30 GB SSD. However, for more comfortable operation and growth potential, 2 vCPU, 4 GB RAM, and 50 GB SSD are recommended. These specifications will provide sufficient performance for the database, cache, and the Outline application itself.

What to choose — VPS or dedicated for this task?

For Outline Wiki, a VPS is sufficient in most cases. A dedicated server becomes relevant if you have a very large team (hundreds of users), extremely high load, or if strict requirements for resource isolation and security are needed, which only a physical server can provide. For typical use in small and medium businesses or for personal projects, a VPS is the optimal and cost-effective choice.

Cannot register the first user, Outline is not sending emails.

This is almost certainly a problem with the email settings in the .env file. Outline uses SMTP or third-party services (Mailgun, SendGrid) to send emails. Ensure that all parameters (MAIL_FROM_EMAIL, SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_SECURE) are specified correctly. Check the Outline container logs for errors related to email sending: docker compose logs outline. It is possible that your VPS provider blocks standard SMTP ports, or the mail server requires additional authentication.

How to update Outline Wiki to a new version?

To update Outline Wiki when deployed via Docker Compose, follow these steps in the ~/outline directory:

        docker compose pull outline # Download the latest version of the Outline image
        docker compose up -d outline # Recreate the Outline container with the new image
        

I forgot the Outline administrator password. How do I reset it?

If you have configured email sending, you can use the "Forgot password" function on the login page. If email is not working or you want to reset the password manually, it is more complex. You will need to access the PostgreSQL database inside the container and manually change or reset the password hash. This is a complex operation requiring accuracy and usually involves executing SQL queries directly against the user table. It is recommended to first ensure that email sending is configured correctly.

Conclusions and Next Steps

Congratulations! You have successfully installed and configured Outline Wiki on your VPS. You now have a powerful, secure, and fully controlled knowledge base for your team or personal projects, accessible via your own domain name with HTTPS protection. You have mastered not only application deployment but also basic server setup, security, and backup strategy, which are valuable skills for any server owner.

What to do next?

• Configure Authentication: Integrate Outline with Google, Slack, Microsoft, or your OIDC provider to simplify user login.
• Monitoring: Set up a monitoring system (e.g., Prometheus + Grafana) to track server status and the performance of Outline, PostgreSQL, and Redis.
• Optimization: As load increases, consider options for optimizing database performance, caching, or scaling VPS resources.