Workload · Running Windmill scripts and flows

Windmill Self Hosted: Your Scripts and Flows on a Server of Your Own

Self-hosting Windmill means running a small Docker Compose stack on a Linux server: PostgreSQL, which also holds the job queue, the web server, a pool of workers that each run one job at a time, an editor helper and Caddy in front. Size the machine by how many jobs you want running at once, because Windmill's own rule is one worker per vCPU with 1 to 2 GB of RAM each, and replace the default admin login the moment the instance starts.

The short version
  1. Default stack: three general workers, one native worker, PostgreSQL 18, Caddy on port 80
  2. Sizing rule from the docs: one worker per vCPU, 1 to 2 GB of RAM each
  3. The default superadmin works until you replace it, even with OAuth on
  4. Back up the whole cluster with pg_dumpall, then copy the file off the machine

What the stack is made of

Windmill splits into a server that answers the browser and the API, and workers that run your code; the two never talk to each other, only to PostgreSQL. The official compose file starts these services:

  • db: PostgreSQL 18, which stores everything, the queue of waiting jobs included. It is exposed only inside the compose network, never on the host.
  • windmill_server: the web app and API, on internal port 8000.
  • windmill_worker: three replicas, each capped at 2048M of memory, for Python, TypeScript, Go, Bash and the other languages in the default tags.
  • windmill_worker_native: one replica for light jobs such as database queries, run in-process by eight native subworkers.
  • windmill_extra: code completion and the debugger for the in-browser editor.
  • caddy: the reverse proxy, publishing port 80 to the world, and port 25 for email triggers.

A worker takes one job at a time and uses whatever processor and memory it has, so your worker count is the number of scripts that can run at once; the rest wait in the queue. A job that goes over its worker's memory cap is killed with exit code 137, and the worker moves on.

How big a server your workers need

Windmill's documentation gives one sizing rule: one worker per vCPU and 1 to 2 GB of RAM. It names no separate figure for the server process or for PostgreSQL, so keep room above these numbers for both.

Jobs at once (workers)Cores for the workersMemory for the workers
4: the compose default, 3 general + 1 native44 to 8 GB
888 to 16 GB
161616 to 32 GB
323232 to 64 GB

Memory is where small machines get caught out. Each default worker container may grow to 2 GB, so the four can claim 8 GB between them before the database has any. Big Python dependencies or a headless browser for reports push a job toward that cap; if one keeps dying with 137, raise memory under that worker's deploy.resources.limits. To run more jobs at once, raise replicas on windmill_worker and run docker compose up -d again.

Why a whole machine suits a job queue

Workers pull from a queue and run flat out, so they work best when the cores you counted are really there. On a dedicated server every core, all the memory and all the disks are yours, with no other customer on the hardware, so a worker sized for one vCPU gets a real core rather than a share of one.

  • Root access: Docker and the privileged worker containers the compose file asks for need no one's permission.
  • An unmetered port: the webhooks, API calls and file transfers your flows make are not counted, and there is no overage charge.
  • Month to month: start with a small machine and move to a bigger one when the queue backs up, with no contract to wait out.
  • A console of your own on rack servers, blades and the m510 and m710x cartridges, so a bad firewall rule does not lock you out.
  • Reinstalls from the control panel, as often as you like.

The server that fits your worker count

Match a class on the dedicated server catalogue to the row of the table you landed on:

  • Compact cartridges suit an instance with the default four workers or fewer. Read the memory on the card: an 8 GB model leaves little after four 2 GB workers, so cut the replicas or pick one with 16 GB or more.
  • Everyday servers, one processor with headroom, suit a team instance that has outgrown the defaults.
  • Two-processor servers, with 16 or 32 cores and memory up to 256 GB, carry a dozen or more workers and a busy database in one box.

A racked server is handed over within 30 minutes of payment approval. To try Windmill with a worker or two before taking a whole machine, a Cloud VPS is a virtual machine that shares its host with other customers, sold as exactly that.

Install it in seven steps

These steps follow Windmill's Docker Compose guide on Ubuntu or Debian. Install Docker Engine and the Compose plugin from Docker's own repository first; Docker Compose on a VPS walks through that part. Then, from an empty folder, fetch the three files Windmill publishes:

curl https://raw.githubusercontent.com/windmill-labs/windmill/main/docker-compose.yml -o docker-compose.yml
curl https://raw.githubusercontent.com/windmill-labs/windmill/main/Caddyfile -o Caddyfile
curl https://raw.githubusercontent.com/windmill-labs/windmill/main/.env -o .env
  1. Check that all three files arrived and are not empty before you go on.
  2. Change the database password before the first start. Choose a long random value of letters and digits (it sits inside a URL) and put it in two places: POSTGRES_PASSWORD under the db service, and in place of changeme in the DATABASE_URL line of .env. The PostgreSQL image applies this password only when it creates an empty data volume, so a change after the first start does nothing.
  3. Point a DNS name at the server. In the caddy service, replace BASE_URL=":80" with BASE_URL=mydomain.com (your name) and uncomment - 443:443. Keep port 80 published: Caddy uses it for redirects and the certificate challenge.
  4. If you will not use email triggers, comment out - 25:25 under caddy so nothing listens on the mail port.
  5. Start the stack with docker compose up -d.
  6. Straight away, open your https:// address and sign in with admin@windmill.dev and changeme. Pick quick setup, set the base URL in the Core step to the public https:// address, and finish the Root login step with your own email and password, which replaces the default superadmin.
  7. Sign out and confirm the default login is refused.

Until step 6 is done, anyone who reaches the address can sign in as superadmin, and the default login works even after OAuth is set up. Never leave a fresh instance waiting on a public address.

Backups, updates and keeping it private

Dump the whole PostgreSQL cluster, not only the windmill database: Windmill keeps extra databases beside it and grants rights to cluster-wide roles, and a single-database dump loses both. Create /backups first, readable only by the account whose crontab runs this line, which is Windmill's own:

0 3 * * * cd /path/to/windmill && (umask 077; docker compose exec -T db pg_dumpall -U postgres > /backups/windmill-$(date +\%F).sql)

The file holds every user's password hash and the secret that signs sessions, so keep it private and copy it off the machine. The dependency cache, the editor cache and Caddy's certificates rebuild themselves. Restoring replaces the database cluster: take a fresh dump of the current state first, check that the file is there and not empty, and only then follow the cluster-replacement steps in Windmill's PostgreSQL 18 upgrade guide.

Updating is docker compose pull, then docker compose up -d. Migrations run at startup, and only jobs still running after Docker's 30-second stop timeout are cut off. The .env file points at the main image tag, so every pull brings the newest build: dump the database before each one. Skip docker image prune -a unless you mean it, because it deletes every image no container is using, other projects' included.

  • Ports: Docker routes published ports before ufw's rules see them, so a ufw rule will not close them. What the compose file publishes is what the internet reaches: keep it to 80, 443 and, only if you use email triggers, 25.
  • Debugger: leave REQUIRE_SIGNED_DEBUG_REQUESTS=true. Windmill warns that turning it off on a reachable instance opens a debugger that runs code without signing in.
  • Docker socket: do not mount it into workers unless you trust every user, because it hands their scripts the host.
  • Isolation: general workers separate jobs with PID namespaces by default; the native worker does not, and nsjail adds filesystem and resource isolation when you enable it.

When one server is the wrong answer

One machine is one point of failure: if it stops, your schedules stop with it. For workers spread over several machines, Windmill recommends its Helm chart on Kubernetes, which you can run yourself on Kubernetes on bare metal.

Check the free edition's limits against your team too. Windmill's pricing page lists the Community Edition at 50 users, 10 of them with SSO, three workspaces and job runs kept up to 30 days, while audit logs, autoscaling and live co-editing need an Enterprise licence from Windmill. And Windmill is yours to run: we keep the hardware and the network going, you keep the software.

Questions people ask

Does running Windmill yourself cost anything?
The Community Edition is free and open source, within the limits on Windmill's pricing page: 50 users and three workspaces among them. The Enterprise Edition needs a licence key entered in the instance settings, and the same key can serve several instances. You pay for the server either way.
Can Windmill use a PostgreSQL server I already run?
Yes. Put its address in DATABASE_URL in .env and set the db service's replicas to 0. On a managed database where you are not a superuser, first run Windmill's init-db-as-superuser.sql with a privileged role to create the windmill_admin and windmill_user roles, then grant both windmill_admin and windmill_user to the user in DATABASE_URL; skip this and the first migration fails.
My database container stopped starting after an update. Why?
The compose file now uses PostgreSQL 18, which cannot read a data volume written by version 16 or earlier, so the container exits instead of starting empty. Follow Windmill's upgrade guide, which dumps the whole cluster with pg_dumpall and loads it into 18. Staying on 16 is supported upstream until November 2028 if you pin both the image and the volume mount.
Do I need a domain name for HTTPS?
For certificates Caddy fetches by itself, yes: the name must point at the server, with ports 80 and 443 reachable. You can also use your own certificate: set BASE_URL=":443", uncomment - 443:443, mount a folder holding cert.pem and key.pem at /certs, and uncomment the tls /certs/cert.pem /certs/key.pem line in the Caddyfile. Either way, set the base URL in the instance settings to the https:// address.

Get a server for your Windmill workers

A whole machine with root access and an unmetered port, handed over within 30 minutes of approval, month to month with no contract.

Choose your server

Read next