Reverse proxy for AWS ECS. Lets you address your docker containers by sub domain.
Last updated Feb 18, 2026
100
Stars
24
Forks
5
Issues
0
Stars/day
Attention Score
27
Topics
Language breakdown
No language data available.
▸ Files
click to expand
README
ecs-nginx-proxy
ecs-nginx-proxy lets you run a nginx reverse proxy in an AWS ECS cluster.
Uses ecs-gen to automatically make containers accessible by subdomain as they are started.
My use case is using a wildcard domain to make per branch test environments accessible by branch.domain.com. Heavily inspired by nginx-proxy.
Security notice
Currently I am only using this for a development cluster in a private network. I advise against using this in a production environment. If you want to do this consider using ecs-gen to create your own nginx config + container setup which is as secure as you need it to be.Sample use case
You want to spin up development environments on AWS ECS for each pull request on your project.
How do you make this easy to use? Do you look up the instance IP and connect directly? The easiest, at least for me, is to setup a wildcard DNS record and route to each deployed branch based on the subdomain, e.g.
*.domain.com, branch.domain.com. This projects enables you to do that.
Usage
Requirements
Wildcard domain like- ELB/ALB for this domain
- ECS Cluster
IAM Policy
EC2 instances in the cluster need a role includingecs:Describe, ecs:List and ec2:Describe
* Easiest is to use AmazonEC2ContainerServiceFullAccess although that gives more permissions than needed
Setup
- Create a new ECS task
codesuki/ecs-nginx-proxy docker image and make port 80 accessible
- Create a new service using the above task and a ELB
Adding containers
Each container you want to make accessible needs to have its corresponding port mapped (can be random mapping) and the environment variableVIRTUAL_HOST set to the hostname it should respond to.
You can customize nginx settings per container by adding environment variables prefixed by NGINXGEN. For examples, you could add an environment variable named NGINXGENclientmaxbodysize to configure the nginx clientmaxbody_size setting.
Sample ECS task and service description
For reference JSON descriptions for the ecs-nginx-proxy task, service and a sample task can be found in theexamples/ folder.
Check out the commands below or just the sample descriptions if you already know how to work with AWS ECS.
To register the sample tasks and services with your AWS ECS cluster run the following commands.
Register task
Requirements
- ECS Cluster
ecs:Describe and ecs:List* permissions (see Requirements above) aws ecs register-task-definition --cli-input-json file://./examples/task.jsonRegister service
Requirements
- ELB or ALB + Target Group
- Service role for the ELB/ALB containing
AmazonEC2ContainerServiceRole
If you use ELB
You need to supply the load balancer name.aws ecs create-service --cluster <NAME> --role <NAME> --load-balancers loadBalancerName=<NAME>,containerName=ecs-nginx-proxy,containerPort=80 --cli-input-json file://./examples/service.jsonIf you use ALB
You need to supply the target group ARN.aws ecs create-service --cluster <NAME> --role <NAME> --load-balancers targetGroupArn=<ARN>,containerName=ecs-nginx-proxy,containerPort=80 --cli-input-json file://./examples/service.jsonRegister sample task
Before running the commands below change theVIRTUALHOST environment variable in examples/samplestask.json to a domain corresponding to your load balancer setup.
aws ecs register-task-definition --cli-input-json file://./examples/sample_task.jsonRegister sample service
aws ecs create-service --cluster <NAME> --service-name sample-service --task-definition sample-task --desired-count 1TODO
- Support SSL connections (for now you can do SSL termination at the ALB)
- Support path based routing (e.g. domain.com/service)
