# Windmill

> Developer platform for scripts and workflows.

- Category: Message Queues & Brokers
- Difficulty: intermediate
- Components: windmill, postgres
- Tags: windmill, scripts, workflows, automation
- Source: https://docker.recipes/messaging/windmill

## Overview

Windmill is a modern developer platform that transforms scripts and code into production-ready workflows with automatically generated UIs, approval systems, and enterprise-grade orchestration. Born from the need to bridge the gap between quick scripts and robust automation platforms, Windmill supports multiple programming languages including Python, TypeScript, Go, Bash, and SQL, making it accessible to diverse development teams. Unlike traditional workflow engines that require proprietary DSLs, Windmill lets developers write in familiar languages while providing enterprise features like audit trails, scheduling, and human-in-the-loop approvals.

This stack combines Windmill with PostgreSQL 16 to create a complete automation platform where PostgreSQL serves as both the execution engine for SQL scripts and the persistent storage layer for workflow definitions, execution history, and user data. The database handles Windmill's complex scheduling requirements, stores detailed execution logs with full audit capabilities, and manages the platform's robust permission system that controls script access and workflow approvals.

Development teams, DevOps engineers, and data analysts who need to quickly deploy internal tools, automate business processes, or create approval workflows will find this combination particularly valuable. The stack excels in environments where multiple stakeholders need to interact with automated processes through generated UIs, where compliance requires detailed audit trails, and where scripts need to evolve from individual tools into organization-wide workflows with proper governance.

## Features

- Multi-language script execution with Python, TypeScript, Go, Bash, and SQL support in a single platform
- Automatic UI generation from script parameters with type inference and validation
- Human-in-the-loop workflows with customizable approval processes and notification systems
- Git synchronization for version control of scripts, flows, and resources with branch-based deployments
- Advanced scheduling engine with cron expressions, event triggers, and dependency management
- Real-time execution monitoring with detailed logs, performance metrics, and error tracking
- Role-based access control with fine-grained permissions for scripts, resources, and workflow execution
- PostgreSQL integration for complex data operations, analytics queries, and persistent workflow state management

## Use cases

- Internal tool development where business users need UI access to developer-written scripts
- DevOps automation requiring approval workflows for infrastructure changes and deployments
- Data pipeline orchestration with mixed SQL queries, Python transformations, and API integrations
- Business process automation where non-technical stakeholders trigger and monitor automated workflows
- Compliance-heavy environments requiring detailed audit trails and approval processes for system changes
- Rapid prototyping of workflow automation before migrating to enterprise platforms
- Cross-team script sharing with governance, documentation, and controlled access to organizational tools

## Prerequisites

- Minimum 2GB RAM recommended for Windmill execution environments and PostgreSQL operations
- Port 8000 available for Windmill web interface access
- Basic understanding of at least one supported language (Python, TypeScript, Go, Bash, or SQL)
- Familiarity with workflow concepts like triggers, scheduling, and approval processes
- PostgreSQL knowledge for database maintenance, backup strategies, and performance tuning
- Git repository access if planning to use version control synchronization features

## docker-compose.yml

```yaml
services:
  windmill:
    image: ghcr.io/windmill-labs/windmill:latest
    container_name: windmill
    restart: unless-stopped
    environment:
      DATABASE_URL: postgres://${DB_USER}:${DB_PASSWORD}@postgres:5432/${DB_NAME}
      BASE_URL: http://localhost:8000
    ports:
      - "8000:8000"
    depends_on:
      - postgres
    networks:
      - windmill

  postgres:
    image: postgres:16-alpine
    container_name: windmill-postgres
    environment:
      POSTGRES_DB: ${DB_NAME}
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - windmill

volumes:
  postgres_data:

networks:
  windmill:
    driver: bridge
```

## .env

```bash
DB_NAME=windmill
DB_USER=windmill
DB_PASSWORD=changeme
```

## Usage notes

- Docs: https://www.windmill.dev/docs/
- Web UI at http://localhost:8000, default admin: admin@windmill.dev / changeme
- Write scripts in Python, TypeScript, Go, Bash, SQL
- Auto-generate UIs from script parameters
- Approval flows and human-in-the-loop workflows
- Git sync for version control of scripts and flows

## Troubleshooting

- Windmill container fails to start with database connection error: Verify PostgreSQL container is fully initialized before Windmill starts, check DATABASE_URL format and credentials
- Scripts fail with import errors or package not found: Windmill requires explicit dependency declarations in script metadata, install packages through the Windmill UI or requirements specification
- Generated UI shows incorrect parameter types: Review script function signatures and type hints, Windmill relies on proper type annotations for UI generation
- Workflow executions appear stuck in pending state: Check Windmill worker processes and resource allocation, verify PostgreSQL connection pool isn't exhausted
- Git sync fails with authentication errors: Ensure proper SSH keys or personal access tokens are configured in Windmill's Git settings
- PostgreSQL container runs out of disk space: Monitor postgres_data volume usage, implement log rotation and consider PostgreSQL maintenance tasks for large execution history

