Self-Hosted Server

Run your own WakeLink stack with the deployer, Docker-based services, shared environment configuration, and reverse proxy integration.

Note

Self-hosting gives you full control over your data and infrastructure. This guide covers Docker deployment (recommended), manual setup, SSL/TLS with Nginx or Caddy, database setup, security, monitoring, and backup.

Why Self-Host?

Benefits of self-hosting:

Benefit	Explanation
Privacy	Your wake commands never leave your infrastructure
Control	Full control over data retention and logging
Customization	Modify server behavior and add features
Compliance	Meet specific regulatory requirements
Cost	No subscription fees for large deployments

Prerequisites

Before starting, make sure you have:

Requirement	Details
Server	Linux VPS or dedicated server (min 1 GB RAM, 1 CPU)
Domain	Domain name pointing to your server (for SSL)
Port 443	Open for HTTPS/WSS traffic
Docker	Docker and Docker Compose installed
SSL Certificate	Let's Encrypt recommended (free)

Docker Deployment (Recommended)

Docker Compose

1 Clone Repository

git clone https://git.deadboizxc.org/wakelink/deployer.git
cd deployer

2 Configure Environment

WakeLink splits configuration in two: non-secret settings live in each service's config.yml (with sensible defaults, in the repo), and secrets live in .env — never committed. You only need to fill in the secrets.

# Copy the secrets template and fill it in
cp .env.example .env
nano .env

Essential secrets (.env):

{\`WAKELINK_SECRET_KEY=<random 64-char string>
POSTGRES_PASSWORD=<your db password>
WAKELINK_DATABASE_URL=postgresql+asyncpg://wakelink:<password>@wakelink-postgres:5432/wakelink\`}

Non-secret settings (public URL, inter-service addresses) come from config.yml defaults and can be overridden per deployment in the compose environment: block — e.g. WAKELINK_PUBLIC_URL, NUXT_FASTAPI_URL. No .env.settings step: services load their own config.yml on start.

3 Launch services

# Run the deployer (clones all service repos and starts containers)
./install.sh

# Check relay server logs
docker logs -f wakelink-relay

# Verify all services are running
docker ps

Manual Setup

1 Install Dependencies

# Python 3.10+ required
sudo apt install python3.10 python3-pip python3-venv

# Clone and setup
git clone https://git.deadboizxc.org/wakelink/relay-ce.git
cd relay-ce
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2 Run Server

# Development
python -m uvicorn src.api:create_app --factory --host 0.0.0.0 --port 8000

# Production (with gunicorn)
gunicorn src.api:create_app --factory \
  --bind 0.0.0.0:8000 \
  --worker-class uvicorn.workers.UvicornWorker \
  --workers 4

3 Systemd Service

# /etc/systemd/system/wakelink.service
[Unit]
Description=WakeLink Server
After=network.target

[Service]
Type=notify
User=wakelink
Group=wakelink
WorkingDirectory=/opt/wakelink
Environment="PATH=/opt/wakelink/venv/bin"
ExecStart=/opt/wakelink/venv/bin/gunicorn src.api:create_app --factory \
  --bind 0.0.0.0:8000 \
  --worker-class uvicorn.workers.UvicornWorker \
  --workers 4
Restart=always

[Install]
WantedBy=multi-user.target

SSL/TLS Setup

WakeLink requires SSL/TLS for WebSocket connections. We recommend Let's Encrypt with Nginx.

Warning

Agents connect via wss:// (WebSocket Secure). A valid TLS certificate is required — self-signed certificates are not supported out of the box. Use Let's Encrypt (free) or another trusted CA.

1 Install Nginx and Get SSL Certificate

# Install Nginx and Certbot
sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

# Get SSL certificate
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

2 Configure Nginx for WebSocket Proxy

Create /etc/nginx/sites-available/wakelink:

server {
    listen 443 ssl http2;
    server_name wakelink-project.org;

    ssl_certificate /etc/letsencrypt/live/wakelink-project.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wakelink-project.org/privkey.pem;

    # WebSocket proxy
    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;

        # WebSocket timeout
        proxy_read_timeout 86400;
    }
}

3 Enable and Restart Nginx

# Enable site
sudo ln -s /etc/nginx/sites-available/wakelink /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Restart Nginx
sudo systemctl restart nginx

Caddy (Alternative)

Caddy provides automatic HTTPS with zero configuration:

wakelink.yourdomain.com {
    reverse_proxy localhost:8000

    # WebSocket configuration
    header Connection "Upgrade"
    header Upgrade "websocket"
}

Caddy automatically obtains and renews SSL certificates from Let's Encrypt.

Database Configuration

Note

Docker Compose: PostgreSQL is included automatically. For manual installation, follow the steps below.

1 Install PostgreSQL

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

2 Create Database and User

# Create database and user
sudo -u postgres psql
CREATE DATABASE wakelink;
CREATE USER wakelink WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE wakelink TO wakelink;
\q

3 Run Database Migrations

# With Docker (deployer)
docker exec -it wakelink-relay python -m alembic upgrade head

# Manual installation
cd relay-ce
python -m alembic upgrade head

Security Best Practices

1 Configure Firewall

# UFW (Ubuntu)
sudo ufw allow 22/tcp   # SSH
sudo ufw allow 80/tcp   # HTTP (for certbot)
sudo ufw allow 443/tcp  # HTTPS/WSS
sudo ufw enable

2 Enable Rate Limiting

Add to your .env file:

RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_BURST=10

Note

Security Checklist:

Use a strong SECRET_KEY (64+ random characters)
Enable SSL/TLS for all connections
Keep database credentials secure
Install regular security updates: apt update && apt upgrade
Monitor logs for suspicious activity
Back up the database regularly

Monitoring & Logging

1 Monitor Application Logs

# Docker logs
docker logs -f wakelink-relay

# Systemd logs
journalctl -u wakelink -f

# Configure log level in .env
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

2 Use Health Check Endpoint

# Check server health
curl https://wakelink.yourdomain.com/health

# Example response:
{
  "status": "healthy",
  "version": "1.2.0",
  "uptime": 86400,
  "connections": 42
}

Backup & Restore

1 Backup Database

# Manual backup
docker exec wakelink-postgres pg_dump -U wakelink wakelink > backup.sql

# Restore from backup
docker exec -i wakelink-postgres psql -U wakelink wakelink < backup.sql

2 Automate Daily Backups

# Add to crontab
0 2 * * * docker exec wakelink-postgres pg_dump -U wakelink wakelink > /backups/wakelink-$(date +\\%Y\\%m\\%d).sql

3 Full System Backup

# Backup everything
tar -czf wakelink-backup.tar.gz \
  /opt/wakelink \
  /etc/nginx/sites-available/wakelink \
  /etc/systemd/system/wakelink.service \
  backup.sql

Troubleshooting

WebSocket Connection Failed

Note

Check Nginx WebSocket configuration
Verify SSL certificate is valid
Test with: wscat -c wss://your-domain.com

Database Connection Error

Note

Verify WAKELINK_DATABASE_URL in .env
Check PostgreSQL is running: systemctl status postgresql
Test connection: psql $WAKELINK_DATABASE_URL

High Memory Usage

Note

Reduce worker count in gunicorn
Set WS_MAX_CONNECTIONS lower
Enable connection pooling

Security — EWSP encryption and token model
Architecture — full service map and data flow
API Reference — REST endpoints and WebSocket protocol