# Windmill Cloudron Package

## Description

Windmill is an open-source developer platform to turn scripts into workflows
and internal apps. Write scripts in Python, JavaScript/TypeScript, Go, Bash,
SQL, PHP, Rust, PowerShell, or Deno; Windmill turns them into sharable HTTP
endpoints, cron-scheduled jobs, and steps in visual **Flows**. It also
generates internal apps from those flows.

This package wraps the official `ghcr.io/windmill-labs/windmill` image in
single-container **server mode** (the server embeds a default worker, so no
separate worker container is needed).

State lives entirely in **PostgreSQL** (Cloudron `postgresql` addon). Windmill
uses Postgres `LISTEN/NOTIFY` for job queuing, so **no Redis is required**.

## Authentication

Windmill supports **OIDC** and **SAML** natively. Unlike many apps, these are
configured in the **in-app Admin Settings UI** (persisted in the database),
not via environment variables.

### Post-install OIDC setup (recommended)

1. Open the Windmill app and sign in as the bootstrap superadmin (the first run
   prints a `SUPERADMIN_SECRET` / creates an admin — see Windmill docs).
2. Go to **Admin Settings → Auth → OIDC**.
3. Enter your identity provider details (Cloudron's OIDC provider issuer,
   client ID, and client secret). The platform OIDC issuer / client creds come
   from your Cloudron instance's app SSO configuration.
4. Save; users can then log in via OIDC.

> OIDC is the preferred auth path for this app. Until OIDC is configured,
   access is limited to the local superadmin account.

## Features

- **Scripts to endpoints**: any script becomes a typed HTTP API + background job
- **Flows**: visually chain scripts with branching, loops, retries, error handling
- **Schedules**: cron-based job scheduling
- **Apps**: generate internal UIs from flows
- **Multi-language**: Python, JS/TS, Go, Bash, SQL, PHP, Rust, PowerShell, Deno
- **Secrets**: encrypted secret management with inheritance
- **Queuing**: Postgres `LISTEN/NOTIFY` (no external broker)

## Configuration

### Ports
- **8000**: Windmill web UI + REST API

### Addons
- **postgresql** (v14): all persistent state, jobs, flows, users, queue
- **localstorage** (`/app/data`): ephemeral job working files

### Environment Variables
The `start.sh` entrypoint derives `DATABASE_URL` automatically from the
Cloudron PostgreSQL addon. The only fixed knob is:

| Variable | Default | Purpose |
|----------|---------|---------|
| `MODE` | `server` | Run mode (server embeds a default worker) |

`DATABASE_URL` is composed at runtime as
`postgres://$USER:$PASS@$HOST:$PORT/$DB?sslmode=disable`.

## Usage

1. Install the package on Cloudron (provisions a PostgreSQL database).
2. On first boot, Windmill runs migrations and bootstraps a superadmin.
3. Sign in, then immediately configure OIDC under Admin Settings (above).
4. Create a script, expose it as a flow/app, schedule it, or call its HTTP endpoint.

## Upstream

- **Repository**: https://github.com/windmill-labs/windmill
- **Image**: `ghcr.io/windmill-labs/windmill:1.514.1`
- **Docs**: https://www.windmill.dev/docs