{"id":18295140,"url":"https://github.com/codesuki/ecs-nginx-proxy","last_synced_at":"2025-09-21T21:06:22.882Z","repository":{"id":83119872,"uuid":"74730741","full_name":"codesuki/ecs-nginx-proxy","owner":"codesuki","description":"Reverse proxy for AWS ECS. Lets you address your docker containers by sub domain.","archived":false,"fork":false,"pushed_at":"2018-08-07T02:20:55.000Z","size":68,"stargazers_count":98,"open_issues_count":5,"forks_count":23,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-21T03:51:16.358Z","etag":null,"topics":["aws","container","continuous-delivery","continuous-deployment","continuous-integration","docker","docker-image","ecs","elastic-container-service","nginx","reverse-proxy"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codesuki.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-25T06:14:12.000Z","updated_at":"2024-01-03T14:14:20.000Z","dependencies_parsed_at":null,"dependency_job_id":"3504c4d6-6faa-4e2e-ba8d-fb3307daf446","html_url":"https://github.com/codesuki/ecs-nginx-proxy","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codesuki%2Fecs-nginx-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codesuki%2Fecs-nginx-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codesuki%2Fecs-nginx-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codesuki%2Fecs-nginx-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codesuki","download_url":"https://codeload.github.com/codesuki/ecs-nginx-proxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247338781,"owners_count":20922995,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","container","continuous-delivery","continuous-deployment","continuous-integration","docker","docker-image","ecs","elastic-container-service","nginx","reverse-proxy"],"created_at":"2024-11-05T14:33:42.055Z","updated_at":"2025-09-21T21:06:22.877Z","avatar_url":"https://github.com/codesuki.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ecs-nginx-proxy\n[![License](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](./LICENSE)\n[![Build Status](http://img.shields.io/travis/codesuki/ecs-nginx-proxy.svg?style=flat)](https://travis-ci.org/codesuki/ecs-nginx-proxy)\n[![nginx latest](https://img.shields.io/badge/nginx-latest-brightgreen.svg?style=flat)](https://hub.docker.com/_/nginx/)\n[![Docker Pulls](https://img.shields.io/docker/pulls/codesuki/ecs-nginx-proxy.svg)](https://hub.docker.com/r/codesuki/ecs-nginx-proxy/)\n\necs-nginx-proxy lets you run a nginx reverse proxy in an AWS ECS cluster. \u003cbr/\u003e\nUses [ecs-gen](https://github.com/codesuki/ecs-gen) to automatically make containers accessible by subdomain as they are started. \u003cbr/\u003e\nMy use case is using a wildcard domain to make per branch test environments accessible by branch.domain.com. Heavily inspired by [nginx-proxy](https://github.com/jwilder/nginx-proxy).\n\n## Security notice\nCurrently 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](https://github.com/codesuki/ecs-gen) to create your own nginx config + container setup which is as secure as you need it to be.\n\n## Sample use case\n![ecs-nginx-proxy](https://github.com/codesuki/ecs-nginx-proxy/raw/master/docs/ecs-nginx-proxy.png)\nYou want to spin up development environments on AWS ECS for each pull request on your project.\nHow do you make this easy to use? Do you look up the instance IP and connect directly? \u003cbr/\u003e\nThe 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`. \u003cbr/\u003e\nThis projects enables you to do that.\n\n## Usage\n### Requirements\n* Wildcard domain like `*.domain.com`\n* ELB/ALB for this domain\n* ECS Cluster\n\n### IAM Policy\n * EC2 instances in the cluster need a role including `ecs:Describe*`, `ecs:List*` and `ec2:Describe*`\n * Easiest is to use `AmazonEC2ContainerServiceFullAccess` although that gives more permissions than needed\n\n### Setup\n* Create a new ECS task\n * Add a container using the `codesuki/ecs-nginx-proxy` docker image and make port 80 accessible\n* Create a new service using the above task and a ELB\n * Connect to the ELB serving the wildcard domain\n\n### Adding containers\nEach container you want to make accessible needs to have its corresponding port mapped (can be random mapping) and the environment variable `VIRTUAL_HOST` set to the hostname it should respond to.\n\nYou can customize nginx settings per container by adding environment variables prefixed by `NGINX_GEN_`. For examples, you could add an environment variable named `NGINX_GEN_client_max_body_size` to configure the nginx [client_max_body_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size) setting.\n\n## Sample ECS task and service description\nFor reference JSON descriptions for the ecs-nginx-proxy [task](./examples/task.json), [service](./examples/service.json) and a [sample task](./examples/sample_task.json) can be found in the `examples/` folder.\nCheck out the commands below or just the sample descriptions if you already know how to work with AWS ECS.\n\nTo register the sample tasks and services with your AWS ECS cluster run the following commands.\n### Register task\n#### Requirements\n* ECS Cluster\n* Cluster EC2 instances need `ecs:Describe*` and `ecs:List*` permissions (see [Requirements](#usage) above)\n```\naws ecs register-task-definition --cli-input-json file://./examples/task.json\n```\n\n### Register service\n#### Requirements\n* ELB or ALB + Target Group\n* Service role for the ELB/ALB containing `AmazonEC2ContainerServiceRole`\n\n#### If you use ELB\nYou need to supply the load balancer name.\n```\naws ecs create-service --cluster \u003cNAME\u003e --role \u003cNAME\u003e --load-balancers loadBalancerName=\u003cNAME\u003e,containerName=ecs-nginx-proxy,containerPort=80 --cli-input-json file://./examples/service.json\n```\n\n#### If you use ALB\nYou need to supply the target group ARN.\n```\naws ecs create-service --cluster \u003cNAME\u003e --role \u003cNAME\u003e --load-balancers targetGroupArn=\u003cARN\u003e,containerName=ecs-nginx-proxy,containerPort=80 --cli-input-json file://./examples/service.json\n```\n\n### Register sample task\nBefore running the commands below change the `VIRTUAL_HOST` environment variable in [examples/samples_task.json](./examples/sample_task.json) to a domain corresponding to your load balancer setup.\n\n```\naws ecs register-task-definition --cli-input-json file://./examples/sample_task.json\n```\n\n### Register sample service\n```\naws ecs create-service --cluster \u003cNAME\u003e --service-name sample-service --task-definition sample-task --desired-count 1\n```\n\n## TODO\n* Support SSL connections (for now you can do SSL termination at the ALB)\n* Support path based routing (e.g. domain.com/service)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodesuki%2Fecs-nginx-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodesuki%2Fecs-nginx-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodesuki%2Fecs-nginx-proxy/lists"}