title: Windmill on AWS ECS

Windmill can be deployed on an ECS cluster. Below are the detailed steps to get a Windmill stack up and running. The number of servers and workers, as well as the instance sizes, should be tuned to your own usecases.

To give a brief overview, we will first create a VPC and an associated security group. This VPC will contain the Database, the instances powering the ECS cluster, and the windmill containers. Then we will create a database on RDS, and finally the ECS cluster.

Once the ECS cluster is running, we will define the tasks definitions and the associated services. Note again that the architecture of your windmill stack very well depends on how you're planning to use Windmill. For this tutorial, we will create a Windmill stack of this shape: 2 windmill servers, 1 "multi-purpose" windmill worker, 1 "native" worker. Windmill LSP and Multiplayer will also be deployed.

1. Go to AWS VPC and create a new one.

a. Name it `windmill-vpc`

a. Choose a CIDR block of your choice. We're going to use `10.0.0.0/16` here. Any value will work, just make sure you'll have enough IPs in the CIDR

a. IPv6 is not required

a. We recommend using at least 2 availability zones, with 2 public subnets and 2 private subnets

a. NAT is required for ECS containers to have access to internet. We recommend creating 2, one in each AZ.

a. We recommend using the S3 Gateway if you're planning to leverage S3 in Windmill

a. Enable both DNS options

1. You will need a security group linked to this VPC. Go to AWS Security Group menu and create a new one

a. Name it `windmill-sg`

a. Link it to the VPC created above

a. Add the following inbound rule: `All traffic FROM this security group`

a. If you want to SSH into the servers, you might want to add the inbound rule: `SSH from MyIP/Anywhere`. This is not required but might help with debugging

a. Add a rule `HTTP traffic FROM anywhere` to be able to hit Windmill Server from your workstation. You can refine security here by having 2 security groups with only one allowing HTTP traffic. And later you'll place only the server in this security group and all the other containers in the more restricted security group. For simplicity, we will just have one security group here.

a. The default outbound rule can be used: `All traffic TO 0.0.0.0/0`

1. Go to AWS RDS

1. Standard create

1. Engine option:

a. PostgreSQL

a. Any recent version of PostgreSQL will work. At the time of writing we're using 16.1-R1

1. Template

a. Choose the template of your choice (Production VS Dev/Test) depending on your needs. Obviously this will greatly impact costs

1. Availability and durability

a. This will be preset depending on the template option you chose. You can customize it depending on your needs.

1. Settings

a. Name it `windmill-db`

a. Leave `postgres` as the username, and choose a string master password. Keep it in a safe place, you will need it in the following steps

1. Instance configuration

a. The instance will be preset depending on the template you chose. Default is usually a good starting point

1. Storage. This is on a per-usecase basis. Just be aware that Windmill stores logs and job results in the database. Depending on the job retention period you want to later configure in Windmill, you might different requirements

a. A good starting point is 400Gib / 12000 IOPS

a. If you chose Multi AZ instance or Standalone instance, it is recommended to turn on autoscaling.

1. Connectivity

a. Don't connect to an EC2 compute resource. Container of the ECS cluster will connect to it using its URL

a. Attach it the VPC created above

a. The DB doesn't need public access

a. Use the security group created above

a. RDS proxy can be a good option in certain cases. It is not required

a. We advise to create a certificate authority and use it here

a. The port can be left to the default: 5432

1. Database authentication

a. Windmill uses Password authentication

1. Monitoring

a. Choose whatever you prefer to monitor your database

1. Additional configuration

a. Initial database name should be set to `windmill`

a. It is advised to enable automated backups

a. Encryption can be set depending on your requirement, same for log export and maintenance.

As said in the introduction, the architecture of your stack depends of your needs. The only requires parts are one Windmill server at least one multi-purpose worker.

1. Go to AWS ECS and Create a new cluster

1. Cluster configuration

a. Name: `windmill-cluster` and leave the namespace the same

1. Infrastructure

a. Uncheck AWS Fargate and check Amazon EC2 instance instead

a. Create a new ASG On-Demand

a. Choose Linux as the operating system. We recommend using either default (x86_64) or ARM64 architecture. WARNING: Whichever you choose, make sure the EC2 instance type chose below is matching the OS architecture

a. Choose an EC2 instance type matching the OS chose above. Here we're using the default Amazon Linux 2 OS, so we will choose a `t3.medium`

a. This Auto-scaling Group will host the 2 Windmill servers, the multi-purpose and native Windmill workers, LSP and multiplayer. The maximum capacity should be at least 4 hosts

a. Allowing SSH access is not required

a. We recommend allocating at least 100GiB of volume size

1. Network settings for EC2 instances

a. Attach it to the VPC and security group created above

a. Make sure to select the PUBLIC subnets if your VPC has private and public ones. The instance should be on the PUBLIC subnets

a. WARNING: You need to TURN ON auto-assign public IP. Otherwise the EC2 agent on the servers will not be able to register the host to the EC2 cluster. This happens if you didn't set a NAT on your VPC

We will create 6 tasks definitions here:

- [REQUIRED] For Windmill Server

- [REQUIRED] For multi-purpose Windmill workers

- [OPTIONAL] For native Windmill workers

- [OPTIONAL] For Windmill LSP

- [OPTIONAL] For Windmill Multiplayer

1. Name: windmill-server

1. Launch Type: AWS EC2 instances

1. OS / Arch: Linux/x86_64 (or make it match your EC2 instance type and OS architecture if you chose something different when creating the ECS cluster)

1. Network mode: awsvpc. This will virtually attach the containers to the VPC networks. The NAT of the VPC is required to give access to the internet to the containers.

1. Task Size: 1vCPU / 1.5GiB Memory (this is good for a cluster of 3 t3.medium. Adapt it to the hardware you provisioned)

1. Task Role: None

1. No Task placement

1. Container:

a. name: windmill-server

a. image: ghcr.io/windmill-labs/windmill:main (or ghcr.io/windmill-labs/windmill-ee:main for EE)

a. Essential container: YES

a. Port mapping: 8000 / TCP / http / HTTP

a. Resource allocation: 1 CPU / 1.5 GiB memory

a. Environment variable: `MODE=server` and `DATABASE_URL=postgres://postgres:<DB_PASSWORD>@DB_HOSTNAME:5432/windmill`. Replace the hostname and password with the ones from the RDS database your created above

a. Turn on log collection for easy debugging

a. Add the following healthcheck: `CMD-SHELL, curl -f http://localhost:8000/api/version || exit 1` / 10s interval / 5s timeout and 5 retries

a. This is it, leave the rest default

1. Name: windmill-worker

1. Launch Type: AWS EC2 instances

1. OS / Arch: Linux/x86_64 (or make it match your EC2 instance type and OS architecture if you chose something different when creating the ECS cluster)

1. Network mode: awsvpc

1. Task Size: 2vCPU / 3.5GiB Memory (this is good for a cluster of 3 t3.medium. Adapt it to the hardware you provisioned)

1. Task Role: None

1. No Task placement

1. Container:

a. name: windmill-worker

a. image: ghcr.io/windmill-labs/windmill:main (or ghcr.io/windmill-labs/windmill-ee:main for EE)

a. Essential container: YES

a. Port mapping: No port mapping for workers

a. Resource allocation: 2 CPU / 3.5 GiB memory

a. Environment variable: `MODE=worker`, `WORKER_GROUP=default` and `DATABASE_URL=postgres://postgres:<DB_PASSWORD>@DB_HOSTNAME:5432/windmill`. Replace the hostname and password with the ones from the RDS database your created above

a. TODO: ellaborate on volumes

a. Turn on log collection for easy debugging

a. This is it, leave the rest default

1. Name: windmill-native-worker

1. Launch Type: AWS EC2 instances

1. OS / Arch: Linux/x86_64 (or make it match your EC2 instance type and OS architecture if you chose something different when creating the ECS cluster)

1. Network mode: awsvpc

1. Task Size: 2vCPU / 3.5GiB Memory (this is good for a cluster of 3 t3.medium. Adapt it to the hardware you provisioned)

1. Task Role: None

1. No Task placement

1. Container:

a. name: windmill-worker

a. image: ghcr.io/windmill-labs/windmill:main (or ghcr.io/windmill-labs/windmill-ee:main for EE)

a. Essential container: YES

a. Port mapping: no port mapping for workers

a. Resource allocation: 2 CPU / 3.5 GiB memory

a. Environment variable: `MODE=worker`, `WORKER_GROUP=native` and `DATABASE_URL=postgres://postgres:<DB_PASSWORD>@DB_HOSTNAME:5432/windmill`. Replace the hostname and password with the ones from the RDS database your created above

a. TODO: ellaborate on volumes

a. Turn on log collection for easy debugging

a. This is it, leave the rest default

1. Name: windmill-lsp

1. Launch Type: AWS EC2 instances

1. OS / Arch: Linux/x86_64 (or make it match your EC2 instance type and OS architecture if you chose something different when creating the ECS cluster)

1. Network mode: awsvpc

1. Task Size: 1vCPU / 1.5GiB Memory (this is good for a cluster of 3 t3.medium. Adapt it to the hardware you provisioned)

1. Task Role: None

1. No Task placement

1. Container:

a. name: windmill-lsp

a. image: ghcr.io/windmill-labs/windmill-lsp:latest

a. Essential container: YES

a. Port mapping: 3001 / TCP / http / HTTP

a. Resource allocation: 1 CPU / 1.5 GiB memory

a. Environment variable: No env variable

a. TODO: ellaborate on volumes

a. Turn on log collection for easy debugging

a. This is it, leave the rest default

1. Name: windmill-multiplayer

1. Launch Type: AWS EC2 instances

1. OS / Arch: Linux/x86_64 (or make it match your EC2 instance type and OS architecture if you chose something different when creating the ECS cluster)

1. Network mode: awsvpc

1. Task Size: 1vCPU / 1.5GiB Memory (this is good for a cluster of 3 t3.medium. Adapt it to the hardware you provisioned)

1. Task Role: None

1. No Task placement

1. Container:

a. name: windmill-multiplayer

a. image: ghcr.io/windmill-labs/windmill-multiplayer:latest

a. Essential container: YES

a. Port mapping: 3002 / TCP / http / HTTP

a. Resource allocation: 1 CPU / 1.5 GiB memory

a. Environment variable: No env variable

a. Turn on log collection for easy debugging

a. This is it, leave the rest default

Similar as above, we will create 6 services.

1. Environment: leave everything default. It will be using the default capacity provider

1. Application type: Service

1. Task definition: select the latest revision of the `windmill-server` task

1. Service name: `windmill-server`

1. Service replica: 2 (to follow what we said above, feel free to tune it to your needs)

1. Networking: Select the VPC created above, and place the services in the PUBLIC subnets. Select the security group created above (or the one allowing traffic on port 80)

1. Load balancer: It's important to create a load balancer here as it will be the entry point to Windmill. Create an Application Load Balancer `windmill-server-lb` with a target group `windmill-server-tg`

1. Environment: leave everything default. It will be using the default capacity provider

1. Application type: Service

1. Task definition: select the latest revision of the `windmill-worker` task

1. Service name: `windmill-worker`

1. Service replica: 2 (to follow what we said above, feel free to tune it to your needs)

1. Networking: Select the VPC created above, and place the services in the PRIVATE subnets. No need for workers to be in the public subnets, as there's NAT in the VPC. Select the security group created above

1. Load balancer: No load balancer, the container is not exposing any port

1. Same a the multi-purpose Windmill worker, except that the task definition should be `windmill-native-worker`

1. Environment: leave everything default. It will be using the default capacity provider

1. Application type: Service

1. Task definition: select the latest revision of the `windmill-lsp` task

1. Service name: `windmill-lsp`

1. Service replica: 1

1. Networking: Select the VPC created above, and place the services in the PRIVATE subnets. No need for workers to be in the public subnets, as there's NAT in the VPC. Select the security group created above

1. Load balancer: Create a load balancer. All we need is actually a Target Group, but using this menu AWS will create both, and we will just have to remove the load balancer later and keep only the target group. Name them `windmill-lsp-lb` and `windmill-lsp-tg`

1. Same as Windmill LSP, using the task definition `windmill-native-worker`.

Here we will add the appropriate routes for requests that the UI will want to make to LSP or Multiplayer. We create 2 load balancers for Windmill LSP and Multiplayer, but only their Target Groups are needed. We will use the Windmill Service Load Balancer to route certain requests to those target groups based on their path.

Go to AWS EC2 Load Balancer menu and start by deleting the load balancers named `windmill-lsp-lb` and `windmill-multiplayer-lb`. Then go to `windmill-server-lb` Load Balancer to update it:

1. Open the HTTP:80 listener and click on the `Add Rule` button on the right

2. Add a Route for LSP

a. Name it `lsp`

a. Add a condition: `Path is /ws/*`

a. Click Next

a. Select target group `windmill-lsp-tg`

a. Give it a priority of `10`

a. Click on Create

a. Add a group for Multiplayer

a. Same as above.

a. The path should be `/ws_mp/*`

a. The target group should be `windmill-multiplayer-tg`

LSP and Multiplayer should now be all set

Go back to the `windmill-server-lb` and copy its DNS. Open it in a new tab. You should see the Windmill Login interface. Follow the instructions to go through the initial Windmill setup

<DocCard

title="Run Locally"

description="Run scripts locally that interact with a Windmill instance."

href="/docs/advanced/self_host/aws_ecs"

/>

<br />