Oct 9, 2024 3 min read

Outline: Your Self-Hosting Setup and Management Guide

Outline: Your Self-Hosting Setup and Management Guide
Table of Contents

Outline is an open-source Knowledge Base and Wiki platform designed for teams, providing a sleek and intuitive interface to collaborate effectively. It’s an excellent choice for self-hosting due to its customization capabilities, data ownership, and privacy-first approach. In this guide, we’ll cover the complete lifecycle of deploying, configuring, and managing Outline, including installation, reverse proxy setup, logging, backups, updates, and leveraging its unique features for maximum productivity.

Installing Outline

πŸ“¦ Docker/Docker Compose Setup

Docker is the easiest way to deploy Outline. Below is a complete docker-compose.yml configuration for setting up Outline with PostgreSQL as its database.


version: "3"

services:

outline:

image: outlinewiki/outline:latest

container_name: outline

ports:

- "3000:3000"

environment:

DATABASE_URL: "postgres://user:password@postgres:5432/outline"

REDIS_URL: "redis://redis:6379"

SECRET_KEY: "your-secret-key"

URL: "https://yourdomain.com"

depends_on:

- postgres

- redis

restart: unless-stopped

volumes:

- ./uploads:/data/uploads

postgres:

image: postgres:13

container_name: postgres

environment:

POSTGRES_USER: user

POSTGRES_PASSWORD: password

POSTGRES_DB: outline

volumes:

- ./postgres-data:/var/lib/postgresql/data

redis:

image: redis:6

container_name: redis

restart: unless-stopped

Deploy this setup with the following commands:


mkdir outline && cd outline

curl -o docker-compose.yml https://your-config-url.com/docker-compose.yml

docker-compose up -d

This will start Outline, PostgreSQL, and Redis. You can access Outline at http://localhost:3000.

πŸš€ Manual Installation

To manually install Outline on a Linux server, follow these steps:

  1. Install dependencies:

sudo apt update

sudo apt install -y nodejs npm postgresql redis

  1. Clone the Outline repository:

git clone https://github.com/outline/outline.git

cd outline

  1. Install Node.js dependencies:

npm install

  1. Configure the environment:

cp .env.sample .env

nano .env

Update the .env file to set database, Redis, and URL configurations.

  1. Start Outline:

npm run build

npm start

Outline will now be accessible at http://localhost:3000.

Configuring Nginx as a Reverse Proxy

🌐 Nginx Configuration

Set up Nginx to route traffic to your Outline instance. Create a server block configuration:


server {

listen 80;

server_name yourdomain.com;

location / {

proxy_pass http://127.0.0.1:3000;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection 'upgrade';

proxy_set_header Host $host;

proxy_cache_bypass $http_upgrade;

}

}

Save this configuration in /etc/nginx/sites-available/outline and enable it:


sudo ln -s /etc/nginx/sites-available/outline /etc/nginx/sites-enabled/

sudo systemctl reload nginx

πŸ”’ SSL/TLS Setup

Secure your Outline instance with Let’s Encrypt:


sudo apt install certbot python3-certbot-nginx

sudo certbot --nginx -d yourdomain.com

Automate certificate renewal:


sudo systemctl enable certbot.timer

πŸ› οΈ Testing and Reloading Nginx

Check the Nginx configuration and reload:


sudo nginx -t

sudo systemctl reload nginx

Logging and Debugging Outline

πŸ—ƒοΈ Enabling Debug Logs

Enable debug logging by modifying the .env file:


DEBUG=1

Restart the Outline service for the changes to take effect.

πŸ“„ Viewing Logs

For Docker-based installations:


docker logs -f outline

For manual installations:


tail -f logs/outline.log

πŸ› οΈ Troubleshooting Common Issues

Check for common errors, such as missing dependencies or misconfigured environment variables, in the logs. Resolve issues by correcting the .env file or installing the appropriate dependencies.

πŸ“€ Exporting Logs

To send logs to an external system like ELK Stack, configure your logging driver in Docker by adding:


logging:

driver: "gelf"

options:

gelf-address: "udp://your-elk-host:12201"

Backup and Restore

πŸ—‚οΈ File-Based Backups

Back up your uploads and configuration:


tar -czvf outline-backup.tar.gz ./uploads ./docker-compose.yml

πŸ”„ Database Backups

Export your PostgreSQL database:


docker exec postgres pg_dump -U user outline > outline-db-backup.sql

Restore the database:


docker exec -i postgres psql -U user outline < outline-db-backup.sql

πŸ“… Automated Backup Scripts

Create a cron job to automate backups:


echo "0 2 * * * tar -czvf /backups/outline-$(date +\%F).tar.gz ./uploads ./docker-compose.yml" | crontab -

Updating and Upgrading Outline

⬆️ Updating Docker Images

Pull the latest Docker image and redeploy:


docker-compose pull

docker-compose up -d

πŸ› οΈ Manual Updates

Pull the latest code and rebuild manually:


git pull origin main

npm install

npm run build

npm start

πŸ” Checking for Updates

Monitor the Outline GitHub repository for new releases and changelogs:


git fetch origin

git status

Leveraging Outline’s Unique Features

πŸ”§ Enabling APIs

Activate Outline’s API by configuring the .env file:


ENABLE_API=true

Test API endpoints with curl:


curl -X GET http://yourdomain.com/api/users -H "Authorization: Bearer your-api-token"

🌟 Advanced Configurations

Integrate third-party tools like Slack by configuring the .env file:


SLACK_KEY=your-slack-integration-key

Restart the service to apply the changes.

Wrapping Up

By following this guide, you’ve successfully deployed, configured, and customized your self-hosted Outline instance. With its flexibility and robust features, Outline empowers you to manage your knowledge base with full control and privacy. Start leveraging the provided configuration and examples to tailor Outline to your team’s needs!

Great! You’ve successfully signed up.
Welcome back! You've successfully signed in.
You've successfully subscribed to Selfhosted Ninja.
Your link has expired.
Success! Check your email for magic link to sign-in.
Success! Your billing info has been updated.
Your billing was not updated.