How to Self-Host Windmill on a VPS (Complete Guide)

Self-hosting has become a popular choice for developers and homelabbers seeking control, privacy, and customization. Windmill, an open-source platform designed for building and managing modern Web apps, can be effectively hosted on a VPS. This guide provides a comprehensive, practical approach to installing and running Windmill on your VPS, emphasizing Docker deployment for ease and scalability.

Why Self-Host Windmill?

Windmill offers a low-code platform with a rich set of features for developing and deploying web applications. Hosting it yourself grants:

• Full data privacy and control
• Customization flexibility
• Cost-effective deployment on affordable VPS providers

Choosing the Right VPS

For hosting Windmill, a basic VPS with sufficient CPU, RAM, and bandwidth suffices. Popular budget VPS providers include:

For a detailed comparison, visit our [full VPS comparison] page.

Prerequisites

• VPS instance (Ubuntu 22.04 LTS recommended)
• SSH access with root privileges
• Basic knowledge of Linux commands
• Docker and Docker Compose installed

Step 1: Prepare Your VPS

Connect via SSH:

ssh root@your-vps-ip

Update your system:

apt update && apt upgrade -y

Install Docker and Docker Compose:

apt install -y docker.io docker-compose
systemctl enable --now docker

Verify installation:

docker --version
docker-compose --version

Step 2: Deploy Windmill Using Docker

Create a directory for your Windmill setup:

mkdir -p ~/windmill
cd ~/windmill

Create a docker-compose.yml file:

version: '3'

services:
  windmill:
    image: windmillfoundation/windmill:latest
    container_name: windmill
    environment:
      - SECRET_KEY=your-secret-key
      - DATABASE_URL=postgres://windmill:password@db:5432/windmill
      - REDIS_URL=redis://redis:6379
    ports:
      - "80:8000"
    depends_on:
      - db
      - redis

  db:
    image: postgres:14
    environment:
      - POSTGRES_DB=windmill
      - POSTGRES_USER=windmill
      - POSTGRES_PASSWORD=password
    volumes:
      - windmill_db_data:/var/lib/postgresql/data/

  redis:
    image: redis:6
    volumes:
      - windmill_redis_data:/data

volumes:
  windmill_db_data:
  windmill_redis_data:

Replace your-secret-key with a strong, unique string, which can be generated via openssl rand -hex 32.

Step 3: Configure and Launch Windmill

Start the containers:

docker-compose up -d

Check logs for errors:

docker-compose logs -f

Once all containers are running, access Windmill via your server’s IP at port 80:

http://your-vps-ip

Follow initial setup prompts to complete configuration.

Step 4: Secure Your Deployment

• Set up a reverse proxy with SSL (Let’s Encrypt) using Nginx.
• Change default passwords and secrets.
• Regularly update your system and containers.

Example Nginx SSL Reverse Proxy

Install Nginx:

apt install -y nginx

Obtain SSL certificate via Certbot:

apt install -y certbot python3-certbot-nginx
certbot --nginx -d yourdomain.com

Configure /etc/nginx/sites-available/windmill:

server {
    listen 80;
    server_name yourdomain.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:80;
        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;
    }
}

Enable Nginx config:

ln -s /etc/nginx/sites-available/windmill /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

FAQs

1. Can I self-host Windmill on a free-tier VPS?

While technically possible, free VPS plans are usually limited in resources such as CPU, RAM, and storage, which are insufficient for reliable Windmill deployment. Additionally, free tiers often have reduced uptime and bandwidth. For a stable experience, a low-cost VPS like Hetzner Cloud or Contabo is recommended. Proper resource allocation ensures Windmill runs smoothly, especially under load. Check your chosen provider’s terms to avoid unexpected disruptions.

2. How secure is deploying Windmill on a VPS?

Security depends on proper configuration. Use strong, unique secrets for your environment variables. Enforce HTTPS with SSL certificates via Certbot. Keep your server and Docker images updated regularly. Limit SSH access and disable root login if possible. Setting up a firewall or fail2ban can help protect against brute-force attacks. For more security practices, see the [self-hosted security guidelines] on r/selfhosted or awesome-selfhosted sites to maintain a robust deployment.

3. What are the common issues when installing Windmill on a VPS?

Common problems include container startup failures due to incorrect environment variables, port conflicts, or resource shortages. Ensure Docker is properly installed and containers have adequate resources allocated. Always check logs with docker-compose logs. Misconfiguration of secrets or network issues can also lead to problems. Troubleshoot by verifying container health, network settings, and environment variables; consult Windmill documentation for specific configuration options.

Final Thoughts

Hosting Windmill yourself empowers you with complete control over your web app development environment. Using Docker simplifies deployment and scaling across various VPS providers. For best results, choose a reliable low-cost provider, secure your setup with SSL, and stay updated. This approach aligns well with the ethos of self-hosted, open-source software and is supported by the vibrant community of self-hosters on [r/selfhosted] and [awesome-selfhosted].

Happy self-hosting!