Self-Hosted Server

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

💡Tip

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

1Clone Repository

bash

git clone https://github.com/wakelink/deployer.git
cd deployer

2Configure Environment

bash

# Copy example environment file
cp .env.example .env

# Edit configuration
nano .env

Essential environment variables:

bash

# Secrets (must change from defaults)
WAKELINK_SECRET_KEY=<generate-random-64-char-string>
POSTGRES_PASSWORD=<your-db-password>

# Public URL of your server
NEXT_PUBLIC_SITE_URL=https://your-domain.com
NEXT_PUBLIC_APP_URL=https://your-domain.com/app
NEXT_PUBLIC_API_URL=https://your-domain.com

3Launch services

bash

# 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

1Install Dependencies

bash

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

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

2Run Server

bash

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

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

3Systemd Service

ini

# /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:9009 \
--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.

1Install Nginx and Get SSL Certificate

bash

# 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

2Configure Nginx for WebSocket Proxy

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

nginx

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:9009;
      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;
  }
}

3Enable and Restart Nginx

bash

# 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:

text

wakelink.yourdomain.com {
  reverse_proxy localhost:9009

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

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

Database Configuration

💡Tip

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

1Install PostgreSQL

bash

# Install PostgreSQL
sudo apt install postgresql postgresql-contrib

2Create Database and User

sql

# 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

3Run Database Migrations

bash

# 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

1Configure Firewall

bash

# 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

2Enable Rate Limiting

Add to your .env file:

bash

RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=60
RATE_LIMIT_BURST=10

💡Tip

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

1Monitor Application Logs

bash

# 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

2Use Health Check Endpoint

bash

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

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

Backup & Restore

1Backup Database

bash

# 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

2Automate Daily Backups

bash

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

3Full System Backup

bash

# 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

💡Tip

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

Database Connection Error

💡Tip

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

High Memory Usage

💡Tip

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

CLI Tools Device Provisioning