Instalar Windmill en un VPS: automatización self-hosted

Por qué autoalojar Windmill en un VPS

Beneficios concretos del autoalojamiento

• Ninguna facturación por ejecución: miles de jobs al día sin factura de computación en la nube.
• Acceso directo a las bases de datos y servicios internos del VPS, sin túnel.
• Secretos y claves API almacenados cifrados en Windmill y que nunca salen de su servidor.
• Formularios de entrada y endpoints REST generados automáticamente para cada script, a partir de la firma de su función main.
• Workers adicionales que se pueden añadir en caliente para absorber los picos de carga.
• Varios workspaces aislados en una misma instancia: uno por equipo, por proyecto o por entorno.
• Versionado: cada despliegue de un script se conserva, y Git Sync envía el workspace a un repositorio Git (incluido en Community Edition para workspaces de 2 usuarios como máximo).

Requisitos técnicos

Dimensionar el VPS según el uso

• La regla del editor: aproximadamente 1 worker por vCPU y de 1 a 2 GB de RAM por worker. Un job que supera el límite de memoria de su worker (2048 MB por defecto) se termina con el código de salida 137.
• Uso individual o prueba: 2 vCPU, 4 GB de RAM y 20 GB de disco, con un solo worker generalista además del worker nativo. Suficiente para scripts programados y algunos webhooks.
• Equipo pequeño: 4 vCPU, 8 GB de RAM y 40 GB de disco. Los tres workers del archivo oficial y PostgreSQL caben en el mismo host sin saturar la memoria.
• Varios equipos o jobs Python pesados: 8 vCPU, 16 GB de RAM y 80 GB de disco para seis a ocho workers. En ese punto, una base PostgreSQL separada simplifica las copias de seguridad y las actualizaciones.

Desplegar Windmill con Docker Compose

1. 01

   Descargar los archivos oficiales

   Conéctese por SSH a su VPS y descargue los tres archivos de referencia publicados en el repositorio de Windmill: el docker-compose.yml, el Caddyfile del reverse proxy y el .env:

   mkdir -p /opt/windmill && cd /opt/windmill
   curl -fsSL https://raw.githubusercontent.com/windmill-labs/windmill/main/docker-compose.yml -o docker-compose.yml
   curl -fsSL https://raw.githubusercontent.com/windmill-labs/windmill/main/Caddyfile -o Caddyfile
   curl -fsSL https://raw.githubusercontent.com/windmill-labs/windmill/main/.env -o .env

   No hace falta clonar todo el repositorio. Estos archivos siguen la rama main: reléalos antes de cada actualización, porque el stack evoluciona (paso a PostgreSQL 18, servicio windmill_extra…).

2. 02

   Rellenar el archivo .env

   El .env solo contiene dos variables. Sustituya la contraseña por defecto de PostgreSQL y fije la imagen en una versión publicada en lugar de main (1.864.1 a 06/11/2026, que debe comprobar en la página de releases de GitHub):

   DATABASE_URL=postgres://postgres:MOT_DE_PASSE_FORT@db/windmill?sslmode=disable
   WM_IMAGE=ghcr.io/windmill-labs/windmill:1.864.1

   Copie la misma contraseña en POSTGRES_PASSWORD, bajo el servicio db del docker-compose.yml. El host db es el nombre del servicio PostgreSQL dentro del stack: no lo sustituya por localhost. Para usar una base existente, apunte DATABASE_URL hacia ella y ponga el servicio db en replicas: 0.

3. 03

   Arrancar el stack

   Lance el conjunto y siga el arranque del servidor:

   docker compose up -d
   docker compose ps
   docker compose logs -f windmill_server

   docker compose ps debe listar db, windmill_server, tres réplicas de windmill_worker, windmill_worker_native, windmill_extra y caddy; el indexador de búsqueda de texto completo (windmill_indexer) se queda en cero réplicas, porque es una función Enterprise. El servidor espera a que PostgreSQL supere su healthcheck y luego aplica él mismo las migraciones de esquema. Escucha en el puerto 8000 de la red Docker, sin publicarse en el host: es Caddy quien recibe el tráfico.

4. 04

   Configurar el reverse proxy y el TLS

   Lo más sencillo es dejar que el Caddy incluido obtenga el certificado Let's Encrypt. En el servicio caddy del docker-compose.yml, descomente el puerto 443 y sustituya BASE_URL=":80" por su dominio; después vuelva a lanzar docker compose up -d:

     caddy:
       ports:
         - 80:80
         - 25:25
         - 443:443
       environment:
         - BASE_URL=windmill.example.com

   Mantenga abierto el puerto 80 para la validación. Si un nginx ya sirve otros sitios en el VPS, elimine el servicio caddy, publique 127.0.0.1:8000:8000 en windmill_server y 127.0.0.1:3000:3000 en windmill_extra, y reproduzca el enrutamiento del Caddyfile: las rutas /ws/, /ws_mp/ y /ws_debug/ van a windmill_extra, y todo lo demás al servidor.

   location ~ ^/ws(_mp|_debug)?/ {
       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;
   }
   location / {
       proxy_pass http://127.0.0.1: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-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
   }

   Las cabeceras Upgrade y Connection son imprescindibles: el editor usa WebSockets para el autocompletado y la depuración. El certificado se obtiene después con certbot --nginx -d windmill.example.com.

5. 05

   Conectarse y asegurar

   Abra https://windmill.example.com e inicie sesión con la cuenta superadmin por defecto, [email protected] / changeme. El asistente del primer arranque propone sustituirla por su propia cuenta: hágalo, porque si se salta el paso las credenciales por defecto siguen activas, y es el fallo más habitual en las instancias Windmill expuestas públicamente. Después, en Instance settings, fije la Base URL en la dirección pública en https://: Windmill la usa para construir las URL de los webhooks y los enlaces de retorno de los flows. Por último, cree su primer workspace con un identificador corto (prod, equipo-datos).

6. 06

   Ajustar el número de workers

   El archivo oficial arranca tres réplicas de windmill_worker, cada una limitada a 2048 MB. En un VPS de 4 GB, baje a uno o dos; en una máquina mayor, suba a un worker por vCPU:

   docker compose up -d --scale windmill_worker=2
   docker compose ps windmill_worker

   Para que el ajuste sea permanente, modifique deploy.replicas del servicio en el docker-compose.yml. El servidor no necesita reiniciarse: los workers se registran solos y aparecen en la página Workers de la interfaz, con su grupo (default o native).

7. 07

   Actualizar Windmill

   Cambie la etiqueta en WM_IMAGE tras leer las notas de versión y después:

   docker compose pull
   docker compose up -d
   docker image prune

   El pull descarga las nuevas imágenes mientras los contenedores antiguos siguen en marcha; al reiniciar, el servidor migra la base por sí solo y los workers terminan sus jobs en curso dentro del plazo de parada de Docker (30 segundos). Haga una copia de seguridad de la base justo antes, y no lance docker image prune -a salvo si el VPS no aloja nada más: el comando también borra las imágenes de los demás proyectos.

Configuración después de la instalación

Los ajustes esenciales

• Workspaces: un workspace aísla scripts, flows, secretos y miembros. Cree uno por equipo o por entorno en lugar de mezclarlo todo, y reserve el rol superadmin a la administración de la instancia.
• Variables y secretos: todas las variables se cifran con una clave simétrica propia del workspace; las marcadas como secretas dejan de mostrarse en la interfaz una vez introducidas. Es el lugar de los tokens de API y las contraseñas, nunca el código del script.
• Recursos: objetos JSON tipados (conexión PostgreSQL, cuenta SMTP, credenciales OAuth). Un parámetro tipado postgresql en un script solo propone entonces los recursos de ese tipo en el formulario generado.
• Programaciones: cada script o flow acepta una o varias programaciones en formato cron de cinco campos, con un campo de segundos opcional al principio. El gestor de errores de programación es una función Enterprise; en Community Edition, vigile las ejecuciones fallidas desde la lista de runs.
• Webhooks: un script se llama de forma asíncrona con /api/w/<workspace>/jobs/run/p/<ruta> (respuesta: el identificador del job) o síncrona con /api/w/<workspace>/jobs/run_wait_result/p/<ruta> (respuesta: el resultado). Autentique con la cabecera Authorization: Bearer <token> en lugar de ?token=, que acaba en los registros de acceso.
• Git Sync: en los ajustes del workspace, vincule un repositorio para enviar a él scripts, flows y recursos en cada despliegue. Gratuito en Community Edition hasta 2 usuarios por workspace; el despliegue automático desde Git está reservado a la edición Enterprise.

Ejemplo: un script Python de principio a fin

# requirements:
# httpx
# psycopg2-binary
from typing import TypedDict

import httpx
import psycopg2


class postgresql(TypedDict):
    host: str
    port: int
    user: str
    dbname: str
    sslmode: str
    password: str


def main(api_url: str, db: postgresql) -> dict:
    resp = httpx.get(api_url, timeout=10)
    resp.raise_for_status()
    rows = [r for r in resp.json() if r.get("active")]
    conn = psycopg2.connect(
        host=db["host"], port=db["port"], user=db["user"],
        password=db["password"], dbname=db["dbname"], sslmode=db["sslmode"],
    )
    with conn, conn.cursor() as cur:
        cur.executemany(
            "INSERT INTO items (id, name) VALUES (%(id)s, %(name)s) ON CONFLICT DO NOTHING",
            rows,
        )
    conn.close()
    return {"candidates": len(rows), "source": api_url}

curl -X POST "https://windmill.example.com/api/w/prod/jobs/run_wait_result/p/f/etl/import_items" \
  -H "Authorization: Bearer $WM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"api_url": "https://api.example.com/items"}'

Resolución de problemas: los errores de un primer despliegue

Síntomas y correcciones

• El contenedor db se detiene justo después de una actualización: el volumen lo creó PostgreSQL 16 y la imagen ha pasado a 18, que se niega a leerlo. Siga el procedimiento de migración de la documentación (volcado completo y restauración), o fije postgres:16 con su antiguo punto de montaje: la versión 16 sigue mantenida hasta noviembre de 2028.
• Job interrumpido con el código 137: ha superado el límite de memoria de su worker. Aumente resources.limits.memory del servicio windmill_worker, o reduzca el tamaño de los datos que el script carga en memoria.
• Servidor o workers incapaces de alcanzar la base: DATABASE_URL apunta a localhost en lugar del servicio db, o la contraseña difiere de POSTGRES_PASSWORD. Corrija el .env y después ejecute docker compose up -d para recrear los contenedores.
• ModuleNotFoundError o instalación de dependencias fallida: el worker descarga los paquetes en la primera ejecución y debe alcanzar pypi.org y files.pythonhosted.org por HTTPS saliente. Detrás de un proxy corporativo, las variables PY_TRUSTED_HOST y PY_INDEX_CERT gestionan la confianza; un índice privado se declara en los Instance settings (edición Enterprise).
• Editor sin autocompletado, depurador mudo: el reverse proxy no enruta /ws/, /ws_mp/ y /ws_debug/ hacia windmill_extra, o elimina las cabeceras Upgrade y Connection. Retome el enrutamiento del Caddyfile oficial.

Windmill, n8n o Temporal

Desplace la tabla