# Windmill Script Platform

> Open-source developer platform for scripts, workflows, and UIs.

- Category: DevOps & CI/CD
- Difficulty: intermediate
- Components: windmill, postgresql, redis, lsp
- Tags: windmill, scripts, workflows, automation, internal-tools
- Source: https://docker.recipes/devops/windmill-scripting

## Overview

Windmill is an open-source developer platform designed to transform scripts into production-grade workflows, UIs, and internal tools. Created to bridge the gap between quick automation scripts and enterprise-grade applications, Windmill allows developers to write code in Python, TypeScript, Go, or Bash and automatically generate web interfaces, APIs, and scheduled workflows. The platform emphasizes developer experience with features like auto-generated UIs, dependency management, and built-in observability.

This deployment creates a complete Windmill environment with four specialized services: the main Windmill server handling the web interface and API, three worker instances for parallel script execution, a Language Server Protocol (LSP) service for enhanced code editing with autocompletion and error checking, and a PostgreSQL database for persistent storage of scripts, workflows, and execution history. The architecture separates concerns effectively, allowing the web interface to remain responsive while workers handle compute-intensive tasks.

This configuration is ideal for development teams wanting to standardize their internal tooling, DevOps engineers looking to create self-service automation portals, and organizations needing to transform ad-hoc scripts into reliable, auditable workflows. The multi-worker setup ensures good performance for concurrent script executions while the integrated LSP provides a superior development experience directly in the browser.

## Features

- Multi-language script support with Python, TypeScript, Go, and Bash runtime environments
- Auto-generated web UIs from script parameters with form validation and custom input types
- Horizontal scaling with three dedicated worker instances for parallel script execution
- Integrated Language Server Protocol support for real-time code completion and error detection
- Built-in dependency management handling npm, pip, and Go module installations automatically
- Workflow orchestration with conditional logic, loops, and error handling capabilities
- Role-based access control with granular permissions for scripts and workflows
- Execution history and audit logs stored in PostgreSQL with detailed runtime metrics

## Use cases

- Internal tool development for customer support teams needing custom data queries and operations
- DevOps automation workflows for deployment pipelines, infrastructure provisioning, and monitoring
- Data engineering tasks including ETL processes, data validation, and automated reporting
- IT operations self-service portals for user management, server provisioning, and maintenance tasks
- Business process automation for invoice processing, data migrations, and compliance checks
- API integration workflows connecting multiple services with custom business logic
- Scheduled maintenance scripts converted into monitored, logged, and alerting-enabled workflows

## Prerequisites

- Docker Engine 20.10+ with Docker Compose V2 support for service health checks
- Minimum 2GB RAM available (1GB for PostgreSQL, 512MB for Windmill server, 256MB per worker)
- Port 8000 available on host system for accessing the Windmill web interface
- Basic understanding of scripting in Python, TypeScript, Go, or Bash for creating workflows
- Familiarity with environment variable configuration for database credentials
- Network connectivity for downloading language dependencies during script execution

## docker-compose.yml

```yaml
services:
  windmill:
    image: ghcr.io/windmill-labs/windmill:main
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      MODE: server
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - windmill-net
    restart: unless-stopped

  windmill-worker:
    image: ghcr.io/windmill-labs/windmill:main
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      MODE: worker
      WORKER_GROUP: default
    depends_on:
      - windmill
    networks:
      - windmill-net
    restart: unless-stopped
    deploy:
      replicas: 3

  windmill-lsp:
    image: ghcr.io/windmill-labs/windmill-lsp:latest
    networks:
      - windmill-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - windmill-net
    restart: unless-stopped

volumes:
  postgres_data:

networks:
  windmill-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=windmill
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=windmill
```

## Usage notes

- Windmill at http://localhost:8000
- Default login: admin@windmill.dev / changeme
- Write scripts in Python, TypeScript, Go, Bash
- LSP for code completion in editor

## Troubleshooting

- Windmill web interface shows 'Database connection failed': Verify POSTGRES_USER, POSTGRES_PASSWORD, and POSTGRES_DB environment variables match between windmill and postgres services
- Scripts fail with 'Worker not available' errors: Check windmill-worker container logs and ensure workers have successfully connected to the main windmill service
- Code completion not working in script editor: Verify windmill-lsp container is running and check browser network tab for WebSocket connection errors to LSP service
- PostgreSQL container fails to start with permission errors: Ensure postgres_data volume has correct ownership and the postgres user can write to the mounted directory
- Script execution timeouts or memory errors: Increase worker container memory limits or reduce the number of concurrent executions in worker configuration
- Cannot access Windmill at localhost:8000: Confirm port 8000 is not in use by another service and check windmill container logs for binding errors

