{"id":20812304,"url":"https://github.com/ukayani/ecs-service","last_synced_at":"2025-09-16T04:07:59.772Z","repository":{"id":57219391,"uuid":"84011442","full_name":"ukayani/ecs-service","owner":"ukayani","description":"A CLI tool for deploying services in AWS Elastic Container Service","archived":false,"fork":false,"pushed_at":"2017-10-12T03:42:13.000Z","size":49,"stargazers_count":12,"open_issues_count":6,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-31T09:11:10.467Z","etag":null,"topics":["aws","ci-cd","cloudformation","containers","docker","ecs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/ukayani.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}},"created_at":"2017-03-05T23:49:39.000Z","updated_at":"2019-01-28T02:27:18.000Z","dependencies_parsed_at":"2022-08-28T23:23:14.392Z","dependency_job_id":null,"html_url":"https://github.com/ukayani/ecs-service","commit_stats":null,"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fecs-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fecs-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fecs-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ukayani%2Fecs-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ukayani","download_url":"https://codeload.github.com/ukayani/ecs-service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252860791,"owners_count":21815568,"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","ci-cd","cloudformation","containers","docker","ecs"],"created_at":"2024-11-17T20:52:46.589Z","updated_at":"2025-09-16T04:07:54.719Z","avatar_url":"https://github.com/ukayani.png","language":"JavaScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# ECS Service\n\n## Overview\n\nThis tool aims to simplify the deployment of docker-based services on\nAmazon's ECS platform.\n\n## How it works\n\nCreation/deployment of ECS services is backed by AWS Cloud Formation.\n\nEvery command in the tool maps to a stack operation in Cloud Formation.\n\nTo use `ecs-service` you need to use a Cloud Formation template\nwhich creates an ECS service along with a Task Definition.\n\nWhen creating your service, you must supply this template along with\nthe version of the service you wish to run. The tool will create a\nCF stack with the name you provide.\n\nAfter the service is created, you can issue commands to update the running\nversion of the service which will result in a stack update.\n\nInstead of having a separate CF template per environment, the idea is to have a single\ntemplate which works across all environments. Because the tool lets you supply\nparameters and environment variables to your docker container, your stack template can\nremain the same between environments.\n\n# Requirements\n\n- NodeJS v6.x or newer\n- A Cloud formation template with an ecs service and task definition defined\n    - Required template parameters:\n        1. `AppVersion` - Must be defined so the version of the service can be supplied by `ecs-service`\n        2. `AppDesiredCount` - Must be defined so the number of instances can be supplied by `ecs-service`\n- An AWS user/role which has permissions to:\n    - DescribeStack\n    - GetTemplate\n    - UpdateStack\n    - CreateStack\n    - DeleteStack\n\n# Installation\n\n```bash\nnpm install -g ecs-service\n```\n\n**AWS REGION**\n\nYou must export the AWS region you are deploying your service to,\nor supply it via the `-r` parameter.\n\n```bash\nexport AWS_REGION=us-east-1\n```\n\n**AWS Credentials**\n\nThe tool will use the standard credential chain used by other aws cli tools.\n\nIf you wish to supply credentials manually see [Options](#aws-credentials)\n\n# Supported Commands\n\n## Deploy Service\n\nTo create or update an existing service you must provide:\n\n- **stackname** - The name of the service you wish to create (this will be the name of the CF Stack)\n- **version**\n    - The version of the service you wish to run. This version should exist in your backing docker repository as a tag.\n    - If you do not wish to change the running version specify `current` as the version. (Only applicable for existing services)\n- **template file** - A JSON Cloud Formation template containing your ECS Service and Task Definition\n- **parameter file** - A file containing a key value JSON object which maps your template parameter's to their values.\n\nTo deploy the service, use the following command:\n\n```bash\n$ ecs-service deploy [stackname] [version] [template_file] [params_file]\n```\n\nThis command will create/update a CF stack with the provided `stackname` and supply the service version via the `AppVersion` parameter.\nFor the remaining non-default parameters, it will use the `parameter file`.\n\nThe command will wait until the successful creation/update of the stack.\n\n### Supplying Environment Variables to your docker container\n\nIf your docker container is configured via Environment Variables you must\nsupply them via the Container Definition's [Environment](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_environment) property.\nThis can be tedious to update when your environment variables change. Hardcoding environment specific values in your task definition would require you to maintain several copies of your task definition; one per environment.\n\n`ecs-service` allows you to supply a `env` file when creating/updating services which\nwill be used to populate the Container Definition's Environment property.\n\nThe `--env-file` parameter can be used to supply an `env` file containing all of\nyour environment variables.\n\n**Example ENV file**\n\n```bash\nEXTERNAL_SERVICE_URI=http://api.myservice.com\nFOO=test\nBAR=blah\n```\n\nEach line defines an environment variable.\n\n**Example Usage**\n\nUsing the `--env-file` parameter, you can supply a `env` file which will be used to pass environment variables to your container.\n\n```bash\n$ ecs-service deploy [stackname] [version] [template_file] [params_file] --env-file \u003cfile\u003e\n```\n\nThis parameter can be used with any of the commands provided.\n\n**Encrypting Environment Variables**\n\nEncrypted environment variables can be supplied to your docker container using [kms-env](https://github.com/ukayani/kms-env). \n\n## Update Service\n\nIf you need to run a new version of your service or update environment variables you can use the simpler `run` command.\nInstead of having to provide a template and parameter files you can use this command if you only need to adjust the version\nor [scale](#setting-the-scale-for-your-service) of your service.\n\nThis command requires:\n\n- **stackname** - The name of the existing service stack.\n- **version**\n    - The version label for the service. A corresponding tag should exist in your docker registry.\n    - If you do not wish to change the running version specify `current` as the version.\n\n```bash\n$ ecs-service update [stackname] [version]\n```\n\nThis command will update your ecs service to use the specified version of your container image.\n\n### Environment Variables\n\nAs mentioned under the [Deploy](#supplying-environment-variables-to-your-docker-service) command, you can use the `--env-file` parameter to supply a file containing\nenvironment variables for your container.\n\n## Stop Service\n\nTo stop a service, you can issue the `stop` command which will set the *desired count* of your service to 0.\n\n```bash\n$ ecs-service stop [stackname]\n```\n\n**Note**: this will not remove/delete your ECS service or Task Definition.\n\n## Destroy Service\n\nTo completely remove the resources associates with your service stack you can use the `destroy` command.\n\nThis command will result in a stack deletion operation.\n\n```bash\n$ ecs-service destroy [stackname]\n```\n\n# Optional Parameters\n\n### Setting the scale for your service\n\nTo specify the number of instances of your service to run, use the `--scale` parameter.\n\n**Example**\n\nTo run two instances of an existing service called `myservice` we can issue the following command:\n\n```bash\n$ ecs-service update myservice 0.1.0 --scale 2\n```\n\n### Specifying AWS Tags for the service stack\n\nIf you need your service stack to have associated tags, you can do so via the `--tag-file` parameter.\n\n**Example**\n\nA tag file is a JSON file with an object where the keys are names of tags to create and values are the tag values.\n\n*Example Tag File - tags.json*\n\n```json\n{\n    \"Owner\": \"Alice\",\n    \"Project\": \"Top Secret\"\n}\n```\n\nGiven the above tag file we can provide it via the `--tag-file` command as follows:\n\n```bash\n$ ecs-service deploy myservice 0.1.0 service.json params.json --tag-file tags.json\n```\n\nThe above command will create `myservice` using the template in `service.json` with the tags `Owner=Alice` and `Project=Top Secret`\n\n### AWS Credentials\n\nTo supply credentials manually you can use the following parameters:\n\n- **--access-key-id** - To specify your access key ID\n- **--secret-access-key** - To specify your secret\n- **--region** - To specify the AWS Region\n\n**Using Profiles**\n\nAlternatively you can supply an AWS credential profile to use via:\n\n- **--profile** - To use a credential profile instead of supplying access key and secret\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukayani%2Fecs-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fukayani%2Fecs-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fukayani%2Fecs-service/lists"}