Skip to content
Klutch.sh Docs

Deploying Outline Server

Introduction

Outline is an open-source VPN solution developed by Jigsaw, a technology incubator within Google. Designed for simplicity and security, Outline makes it easy to create and share VPN access without the complexity of traditional VPN configurations. The server runs Shadowsocks, providing encrypted proxy connections that are difficult to detect and block.

Outline consists of two components: the Outline Manager for server administration and the Outline Client for connecting. The Manager generates access keys that users import into the Client app, enabling VPN access with a single click. This design makes Outline ideal for journalists, activists, and organizations that need secure internet access in restrictive environments.

Key highlights of Outline:

  • Easy Setup: Deploy a VPN server in minutes
  • One-Click Access: Share access keys that configure clients automatically
  • Cross-Platform: Clients for Windows, macOS, Linux, iOS, and Android
  • Shadowsocks Protocol: Encrypted, resistant to detection and blocking
  • No Logs: Designed with privacy in mind, minimal data retention
  • Open Source: Fully auditable codebase
  • Data Limits: Optional per-key data limits for fair usage
  • Multiple Keys: Create separate access keys for different users
  • Self-Hosted: Full control over your VPN infrastructure
  • Free: No licensing costs or subscription fees

This guide walks through deploying Outline Server on Klutch.sh using Docker, creating access keys, and distributing VPN access to users.

Why Deploy Outline on Klutch.sh

Deploying Outline on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically builds and deploys your VPN server. Push to GitHub, and your server deploys without manual intervention.

Persistent Configuration: Attach persistent volumes for server configuration and access keys. Your VPN setup survives container restarts.

Reliable Uptime: Your VPN server runs 24/7 with consistent availability.

Geographic Options: Choose deployment regions for optimal latency or to access region-specific content.

Scalable Resources: Allocate bandwidth and resources based on expected usage.

Custom Domains: Optionally use custom domains for management access.

Privacy: Keep your VPN infrastructure under your control.

Prerequisites

Before deploying Outline on Klutch.sh, ensure you have:

  • A Klutch.sh account
  • A GitHub account with a repository for your Outline configuration
  • Basic familiarity with Docker and containerization concepts
  • Outline Manager application (for server management)
  • Outline Client for testing connections

Understanding Outline Architecture

Outline uses a simple architecture:

Shadowsocks Server: Handles encrypted proxy connections from clients using the Shadowsocks protocol.

Management API: HTTPS API for creating and managing access keys, secured with TLS certificates.

Outline Manager: Desktop application that communicates with the Management API to administer the server.

Outline Client: Applications for various platforms that connect to the server using access keys.

Preparing Your Repository

Create a GitHub repository containing your Dockerfile and configuration.

Repository Structure

outline-deploy/
├── Dockerfile
├── .dockerignore
└── README.md

Creating the Dockerfile

Create a Dockerfile for Outline:

FROM quay.io/outline/shadowbox:stable


# Create persistent data directory
RUN mkdir -p /opt/outline


# Outline uses these ports:
# - 8080: Management API (HTTPS)
# - 443: Default Shadowsocks port (can vary)
EXPOSE 8080
EXPOSE 443


# Persisted state directory
ENV SB_STATE_DIR=/opt/outline/persisted-state


# Use the default entrypoint

Environment Variables Reference

VariableDescription
SB_STATE_DIRDirectory for persisted server state
SB_API_PORTManagement API port (default: 8080)
SB_API_PREFIXAPI URL prefix
SB_CERTIFICATE_FILECustom TLS certificate path
SB_PRIVATE_KEY_FILECustom TLS private key path

Deploying Outline on Klutch.sh

Follow these steps to deploy your Outline VPN server:

    Push Your Repository to GitHub

    Initialize and push your repository:

    Terminal window
    git init
    git add Dockerfile .dockerignore README.md
    git commit -m "Initial Outline Server configuration"
    git remote add origin https://github.com/yourusername/outline-deploy.git
    git push -u origin main

    Create a New Project on Klutch.sh

    Navigate to the Klutch.sh dashboard and create a new project named “outline” or “vpn”.

    Create a New App

    Within your project, create a new app. Connect your GitHub account and select the repository containing your Outline Dockerfile.

    Configure Network Traffic

    Configure ports for your deployment:

    • Port 8080: Management API (HTTPS)
    • Port 443: Shadowsocks connections (or custom port)

    Note: Outline may require TCP/UDP passthrough. Verify Klutch.sh supports the required network configuration.

    Attach Persistent Volumes

    Add persistent storage:

    Mount PathRecommended SizePurpose
    /opt/outline/persisted-state1 GBServer state and access keys

    Deploy Your Application

    Click Deploy to start the build process.

    Retrieve Management Credentials

    After deployment, access the container logs to find the Management API URL and credentials:

    1. View deployment logs
    2. Look for the API URL with the unique prefix
    3. Note the certificate fingerprint
    4. Save these for the Outline Manager

    Connect Outline Manager

    Open Outline Manager:

    1. Click “Add a server”
    2. Select “Set up Outline anywhere”
    3. Paste the management URL
    4. Verify the certificate fingerprint
    5. Connect to your server

Using Outline Manager

Creating Access Keys

Generate keys for users:

  1. Open Outline Manager
  2. Select your server
  3. Click “Add key”
  4. Name the key (e.g., “John’s Phone”)
  5. Copy or share the access link

Sharing Access Keys

Distribute VPN access:

  1. Generate an access key
  2. Click “Share” on the key
  3. Copy the access link
  4. Send to the user securely

The access link contains everything needed to configure the client.

Managing Data Limits

Set per-key data limits:

  1. Click on a key in the Manager
  2. Click the data limit setting
  3. Set a monthly limit (e.g., 10 GB)
  4. Save the limit

Renaming Keys

Identify keys easily:

  1. Click on a key
  2. Click the name to edit
  3. Enter a descriptive name
  4. Save

Revoking Access

Remove user access:

  1. Find the key in Outline Manager
  2. Click the delete button
  3. Confirm deletion
  4. The key is immediately invalidated

Client Setup

Installing Outline Client

Download the Outline Client:

Connecting with an Access Key

Use an access key:

  1. Open Outline Client
  2. Click “Add server” or the + button
  3. Paste the access link
  4. The server is added and connected automatically

Managing Connections

Client features:

  • Connect/disconnect with one tap
  • Multiple server support
  • Auto-reconnect on network changes
  • Traffic statistics

Advanced Configuration

Custom Ports

Use non-standard ports:

  1. Modify the Dockerfile to expose different ports
  2. Configure Shadowsocks to use the custom port
  3. Update firewall rules accordingly

Custom Domain

Use your domain for the management API:

  1. Configure DNS to point to your server
  2. Provide custom TLS certificates
  3. Update the API URL in Outline Manager

Metrics and Monitoring

Monitor server usage:

  1. Outline Manager shows per-key data usage
  2. View total server bandwidth
  3. Monitor active connections

Security Best Practices

Access Key Management

  • Create individual keys for each user
  • Use descriptive names for easy management
  • Regularly audit active keys
  • Delete unused keys promptly

Server Security

  • Keep the server image updated
  • Monitor for unusual traffic patterns
  • Use data limits to prevent abuse
  • Review logs periodically

Communication Security

  • Share access links securely
  • Avoid posting keys publicly
  • Use encrypted channels for distribution
  • Consider key expiration for temporary access

Use Cases

Personal VPN

Use Outline for personal privacy:

  • Secure public WiFi connections
  • Access region-restricted content
  • Bypass network restrictions

Organization VPN

Provide team access:

  • Create keys for each team member
  • Set appropriate data limits
  • Revoke access when members leave

Journalism and Activism

Protect communications:

  • Distribute keys to trusted contacts
  • Evade network censorship
  • Maintain anonymous connections

Troubleshooting Common Issues

Cannot Connect to Server

Symptoms: Outline Client fails to connect.

Solutions:

  • Verify server is running
  • Check port accessibility
  • Ensure access key is valid
  • Try a different network

Manager Cannot Connect

Symptoms: Outline Manager shows connection error.

Solutions:

  • Verify API URL is correct
  • Check certificate fingerprint matches
  • Ensure port 8080 is accessible
  • Review server logs

Slow Connections

Symptoms: VPN connection is slow.

Solutions:

  • Check server resource allocation
  • Verify bandwidth is not limited
  • Try connecting to a different port
  • Check for network congestion

Keys Not Working

Symptoms: New keys fail to connect.

Solutions:

  • Verify key was generated successfully
  • Check server is reachable
  • Ensure client app is updated
  • Regenerate the key if needed

Additional Resources

Conclusion

Deploying Outline on Klutch.sh provides a simple, secure VPN solution that you control. With easy access key distribution and cross-platform clients, Outline makes VPN access accessible to everyone.

The combination of persistent storage for server state, reliable uptime, and flexible network configuration makes Klutch.sh suitable for hosting Outline. Whether protecting personal browsing or providing secure access for an organization, your self-hosted VPN gives you privacy and control.

Generate access keys, share them with your users, and enjoy secure, encrypted internet access anywhere.