Deploy Outline Knowledge Base on a VPS: A Step-by-Step Guide

Deploying the Outline knowledge base on a Virtual Private Server (VPS) offers complete control over your data and infrastructure, making it an excellent choice for teams and individuals seeking a self-hosted solution. This guide provides a step-by-step process for setting up Outline using Docker Compose, Nginx as a reverse proxy, and Let's Encrypt for SSL, typically on an Ubuntu 24.04 LTS server. The installation involves configuring essential services like PostgreSQL and Redis, ensuring a secure and scalable knowledge management platform.

Outline is an open-source, collaborative knowledge base designed for teams. It offers a clean interface, Markdown support, and robust search capabilities, positioning it as a strong alternative to proprietary solutions. Self-hosting Outline on a VPS means you retain full ownership of your intellectual property and can customize the environment to meet specific security or performance requirements. As of April 2026, Outline continues to be actively developed, with its Docker-based deployment being the recommended approach for ease of setup and maintenance.

Choosing Your VPS and Initial Server Setup

Selecting the right VPS is the foundational step for deploying Outline. A server with at least 2GB of RAM and 2 CPU cores is recommended for small to medium teams, especially when running PostgreSQL and Redis alongside Outline. Providers such as Valebyte offer managed VPS solutions that can simplify the underlying server administration, allowing you to focus more on your Outline deployment. For our guide, we'll assume a fresh Ubuntu 24.04 LTS server, which provides a stable and widely supported environment.

Before installing any applications, ensure your VPS is up-to-date and secure. This involves updating packages, creating a non-root user with sudo privileges, and configuring a firewall. An initial server hardening checklist is crucial for long-term security. You can find a comprehensive guide for initial setup in Nelsa's Ubuntu 24.04 VPS Hardening Checklist for Initial Server Setup.

First, connect to your VPS via SSH as the root user. Update your package list and upgrade existing packages to their latest versions:

sudo apt update && sudo apt upgrade -y

Next, install essential utilities for network and file management:

sudo apt install -y curl wget git ufw

Configure the UFW (Uncomplicated Firewall) to allow SSH, HTTP, and HTTPS traffic. This protects your server from unauthorized access while allowing web services to operate:

sudo ufw allow OpenSSHsudo ufw allow http sudo ufw allow httpssudo ufw enable

Confirm the firewall status to ensure rules are active:

sudo ufw status

Installing Docker and Docker Compose

Outline is designed for containerized deployment using Docker. Installing Docker Engine and Docker Compose is a prerequisite for running Outline and its dependencies efficiently. As of 2026-04, Docker Engine 25.0 and Docker Compose 2.24 are stable and widely used versions. The official Docker documentation provides the most current installation instructions and best practices, available on Docker's official website.

First, remove any old versions of Docker that might be present:

for pkg in docker.io docker-doc docker-compose docker-ce docker-ce-cli containerd.io runc; do sudo apt remove $pkg; done

Install Docker's dependencies and add the official Docker GPG key and repository to your system:

sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg echo \  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \  sudo tee /etc/apt/sources.list.d/docker.list > /dev/nullsudo apt update

Now, install Docker Engine, containerd, and Docker Compose:

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify the Docker installation by running the hello-world container:

sudo docker run hello-world

To avoid using sudo with Docker commands, add your user to the docker group:

sudo usermod -aG docker $USERnewgrp docker

Log out and log back in (or open a new terminal session) for the group changes to take effect. You can then verify by running docker run hello-world without sudo.

Configuring Outline with Docker Compose

Outline relies on several services to function correctly: a PostgreSQL database for data storage and Redis for caching and real-time features. Docker Compose simplifies the orchestration of these services. Create a new directory for your Outline project and navigate into it:

mkdir ~/outlinecd ~/outline

Create a docker-compose.yml file with the following content. This configuration defines the Outline application, PostgreSQL, and Redis containers, linking them together:

version: '3.8'services:  outline:    image: outline/outline:latest    env_file:      - ./.env    ports:      - "3000:3000"    depends_on:      - postgres      - redis    restart: always  postgres:    image: postgres:15-alpine    environment:      POSTGRES_DB: ${POSTGRES_DATABASE}      POSTGRES_USER: ${POSTGRES_USER}      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}    volumes:      - postgres_data:/var/lib/postgresql/data    restart: always  redis:    image: redis:7-alpine    volumes:      - redis_data:/data    restart: alwaysvolumes:  postgres_data:  redis_data:

Next, create the .env file in the same directory. This file will store sensitive environment variables for Outline, PostgreSQL, and Redis. Replace placeholders like YOUR_SECRET_KEY, YOUR_POSTGRES_PASSWORD, and your.domain.com with your actual values. You can generate a strong secret key using openssl rand -base64 32.

# Application settingsPORT=3000URL=https://your.domain.comSECRET_KEY=YOUR_SECRET_KEY# Database settingsPOSTGRES_DATABASE=outlinePOSTGRES_USER=outlineuserPOSTGRES_PASSWORD=YOUR_POSTGRES_PASSWORDPOSTGRES_HOST=postgresPOSTGRES_PORT=5432# Redis settingsREDIS_URL=redis://redis:6379REDIS_HOST=redisREDIS_PORT=6379# Email settings (optional, for notifications)[email protected]_HOST=your.smtp.server.comSMTP_PORT=587SMTP_USERNAME=your_smtp_usernameSMTP_PASSWORD=your_smtp_passwordSMTP_TLS_REJECT_UNAUTHORIZED=false# External authentication (optional, e.g., Google, Slack)GOOGLE_CLIENT_ID=GOOGLE_CLIENT_SECRET=SLACK_CLIENT_ID=SLACK_CLIENT_SECRET=

Run docker compose up -d to start all services. This command downloads the necessary Docker images, creates the containers, and starts them in the background. The initial setup might take a few minutes depending on your internet connection and VPS performance.

docker compose up -d

Setting up Nginx as a Reverse Proxy

To serve Outline securely over HTTPS and route requests from your domain, you'll configure Nginx as a reverse proxy. Nginx 1.27, released in August 2024, is known for its performance and reliability in this role. It will listen for incoming web requests on ports 80 (HTTP) and 443 (HTTPS) and forward them to the Outline container running on port 3000. This also allows us to terminate SSL connections at Nginx, simplifying the Outline application configuration.

Install Nginx on your VPS:

sudo apt install -y nginx

Create a new Nginx configuration file for your Outline domain. Replace your.domain.com with your actual domain name:

sudo nano /etc/nginx/sites-available/outline.conf

Add the following Nginx configuration. This sets up a basic HTTP listener and a placeholder HTTPS block which Certbot will later populate:

server {    listen 80;    server_name your.domain.com;    location / {        return 301 https://$host$request_uri;    }}server {    listen 443 ssl;    server_name your.domain.com;    ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem; # Managed by Certbot    ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem; # Managed by Certbot    include /etc/letsencrypt/options-ssl-nginx.conf; # Managed by Certbot    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # Managed by Certbot    location / {        proxy_pass http://localhost:3000;        proxy_set_header Host $host;        proxy_set_header X-Real-IP $remote_addr;        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;        proxy_set_header X-Forwarded-Proto $scheme;        proxy_http_version 1.1;        proxy_buffering off;        proxy_cache_bypass $http_pragma $http_authorization;        proxy_no_cache $http_pragma $http_authorization;        proxy_read_timeout 3600; # Long timeout for potential large uploads/downloads    }}

Create a symbolic link from sites-available to sites-enabled to activate the configuration, then test Nginx syntax and reload:

sudo ln -s /etc/nginx/sites-available/outline.conf /etc/nginx/sites-enabled/sudo nginx -t sudo systemctl reload nginx

Ensuring your Nginx configuration is correct before applying it is vital. The sudo nginx -t command checks for syntax errors, preventing potential service disruptions caused by misconfigurations.

Securing Outline with Let's Encrypt SSL

HTTPS is mandatory for any public-facing web application, especially a knowledge base containing sensitive information. Let's Encrypt provides free, automated SSL certificates. Certbot is the recommended client for obtaining and renewing these certificates. As of 2026-04, Certbot 2.9 is the latest stable version, offering robust features for Nginx integration. The process involves installing Certbot and then running a command to generate and install the SSL certificate.

Install Certbot and the Nginx plugin:

sudo apt install -y certbot python3-certbot-nginx

Obtain and install the SSL certificate for your domain. Replace your.domain.com with your actual domain and [email protected] with your email address:

sudo certbot --nginx -d your.domain.com --email [email protected] --agree-tos --no-eff-email

Certbot automatically modifies your Nginx configuration to include the SSL certificate paths and sets up automatic renewal. You can test the renewal process with a dry run:

sudo certbot renew --dry-run

This ensures that your certificates will renew automatically before they expire, typically every 90 days. For more advanced troubleshooting, refer to Nelsa's guide on Fixing Let's Encrypt Rate Limit Reached Errors in 2026.

DNS Configuration and Initial Outline Setup

Before you can access your Outline knowledge base, you need to configure your domain's DNS records to point to your VPS's IP address. Create an 'A' record for your domain (e.g., your.domain.com) that points to the public IPv4 address of your VPS. If you plan to use a subdomain (e.g., kb.your.domain.com), create an 'A' record for that subdomain. DNS changes can take a few minutes to several hours to propagate globally, a process known as DNS propagation.

Once DNS has propagated and your Nginx and Certbot configurations are complete, navigate to https://your.domain.com in your web browser. You should be greeted by the Outline setup screen. Outline provides several authentication options, including email/password, Google, and Slack. Choose your preferred method and complete the initial administrator account creation. After creating your account, you can start populating your knowledge base with documents.

Here's a comparison of common authentication methods for Outline:

Maintaining and Securing Your Outline Deployment

Maintaining a self-hosted Outline instance involves regular updates, backups, and monitoring. Staying current with Docker image updates for Outline, PostgreSQL, and Redis ensures you benefit from the latest features, security patches, and performance improvements. You can update your Docker containers by pulling the latest images and recreating the containers:

cd ~/outline # Navigate to your Outline directorydocker compose pull # Pull latest imagesdocker compose up -d # Recreate containers with new images

Regular backups of your PostgreSQL database and Outline's configuration are critical. For PostgreSQL, you can use pg_dump from within the container. Consider using tools like restic or rsync to regularly back up your postgres_data and redis_data volumes, along with your .env and docker-compose.yml files to an offsite location. A guide on Vaultwarden Self-Hosted with Cloudflare Tunnel also touches on backup strategies applicable to other self-hosted applications.

Monitoring your VPS resource usage (CPU, RAM, disk I/O) is essential for identifying performance bottlenecks or potential issues. Tools like htop, glances, or more advanced solutions like Prometheus and Grafana can provide insights into your server's health. Implement security best practices such as strong passwords, SSH key authentication (if not already done), and keeping your operating system and Docker components updated. Periodically reviewing Nginx logs and Outline's application logs can help detect unusual activity or errors. Additionally, consider using a tool like Fail2ban to automatically block malicious IP addresses attempting brute-force attacks on your SSH or web services. If you encounter issues, Nelsa has a guide on Fail2ban Not Banning IP Addresses: Troubleshooting Guide for 2026.

Troubleshooting Common Outline Deployment Issues

Even with careful planning, you might encounter issues during or after your Outline deployment. Understanding common problems and their solutions can save significant troubleshooting time. The first step in debugging Docker-related issues is to check the logs of your containers.

To view logs for a specific service (e.g., Outline):

docker compose logs outline

If your Outline container fails to start, common causes include incorrect environment variables in your .env file (e.g., wrong database credentials or secret key) or a misconfigured docker-compose.yml. Double-check all values, especially database connection details and the SECRET_KEY.

If you're seeing a 502 Bad Gateway error from Nginx, it usually indicates that Nginx cannot connect to the Outline application. This could be due to Outline not running, running on a different port than Nginx expects, or firewall issues blocking Nginx from communicating with the Docker container. Verify that the Outline container is running and accessible from the host system:

docker ps # Check if outline container is upcurl http://localhost:3000 # Test if Outline is listening on port 3000

For Nginx 502 errors, inspect the Nginx error logs, typically located at /var/log/nginx/error.log. These logs often provide specific details about why the connection failed. Nelsa's guide on Nginx 502 Bad Gateway Diagnostics Checklist offers further troubleshooting steps.

SSL certificate issues, such as "NET::ERR_CERT_DATE_INVALID" or "Your connection is not private," indicate a problem with your Let's Encrypt certificate. This might mean the certificate expired, failed to renew, or was not correctly installed. Run sudo certbot certificates to check the status of your installed certificates and their expiration dates. If necessary, try manually renewing with sudo certbot renew --force-renewal.

Frequently Asked Questions