{"id":13415865,"url":"https://github.com/byrnedo/capitan","last_synced_at":"2025-04-09T20:20:34.346Z","repository":{"id":57502936,"uuid":"48820776","full_name":"byrnedo/capitan","owner":"byrnedo","description":"Capitan is a tool for managing multiple Docker containers","archived":false,"fork":false,"pushed_at":"2017-06-07T09:46:56.000Z","size":1581,"stargazers_count":30,"open_issues_count":3,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-23T22:12:18.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/byrnedo.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":"2015-12-30T21:49:14.000Z","updated_at":"2025-03-11T16:30:01.000Z","dependencies_parsed_at":"2022-09-02T01:52:14.921Z","dependency_job_id":null,"html_url":"https://github.com/byrnedo/capitan","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Fcapitan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Fcapitan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Fcapitan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/byrnedo%2Fcapitan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/byrnedo","download_url":"https://codeload.github.com/byrnedo/capitan/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248104102,"owners_count":21048282,"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":[],"created_at":"2024-07-30T21:00:52.625Z","updated_at":"2025-04-09T20:20:34.293Z","avatar_url":"https://github.com/byrnedo.png","language":"Go","funding_links":[],"categories":["Container Operations"],"sub_categories":["Container Composition"],"readme":"# Capitan\n\n[![GoDoc](https://godoc.org/github.com/byrnedo/capitan?status.svg)](https://godoc.org/github.com/byrnedo/capitan)\n\nCapitan is a tool for managing multiple Docker containers based largely on [crowdr](https://github.com/polonskiy/crowdr)\n\nCapitan is only a wrapper around the docker cli tool, no api usage whatsoever (well... an `inspect` command here and there).\nThis means it will basically work with all versions of docker.\n\n    $ capitan up\n\n    Run arguments changed, doing blue-green redeploy: capitan_redis_green_1\n    Running capitan_redis_blue_1\n    cd939956f332391489d0383610d9da2c420595d495934c3221376dbf68854316\n    Removing old container capitan_redis_green_1...\n    Already running capitan_mongo_blue_1\n    Already running capitan_nats_blue_1\n    Already running capitan_app_blue_1\n\n## Features\n\n- Provides commands which operate on collection of containers.\n- Uses predefined description of containers from readable configuration file.\n- Can use any docker run option that is provided by your docker version.\n- The order of starting containers is defined in configuration file.\n- The order of stopping containers is the reverse of the order of starting.\n- Easy to install, compiled static go binaries available for linux, and mac. It doesn't require any execution environment or other libraries.\n- Allows the use of bash as hooks for many capitan commands.\n- [Blue/Green](https://docs.cloudfoundry.org/devguide/deploy-apps/blue-green.html) deployment - option to only remove original container when starting new version of same container if it starts and passes hook commands.\n\n\n## Installation\n\nHead over to the [releases](https://github.com/byrnedo/capitan/releases) page to download a pre-build binary or deb file.\n\nOr using go:\n\n    go get github.com/byrnedo/capitan\n\n## Commands\n\n### Invasive commands\n\n#### `up`\nCreate then run or update containers \nRecreates if:\n\n1. ~~If newer image is found it will remove the old container and run a new one~~ No longer does this as capitan can't know which node to check images for when talking to a swarm.\n2. Container config has changed\n    \nStarts stopped containers\n\n    capitan up\n    # Optionally can attach to output using `--attach|-a` flag.\n    capitan up -a\n\n#### `create`\nCreate but don't run containers\n\n    capitan create\n    \n#### `start`\nStart stopped containers\n\n    capitan start\n    # Optionally can attach to output using `--attach|-a` flag.\n    capitan start -a\n    \n#### `scale`\nStart or stop instances of a container until required amount are running\n\n    # run 5 instances of mysql\n    capitan scale mysql 5\n    \nNOTE: for containers started via this command to be accepted by further commands, the config output must be altered to state the required instances\n\n##### `restart`\t\nRestart containers\n    \n    capitan restart\n    # Further arguments passed through to docker, example `capitan start -t 5`\n    capitan restart -t 10\n\n##### `stop`\t\nStop running containers\n    \n    capitan stop\n    # Further arguments passed through to docker, example `capitan stop -t 5`\n    capitan stop -t 10\n    \n##### `kill`\t\nKill running containers using SIGKILL or a specified signal\n    \n    capitan kill\n    # Further arguments passed through to docker, example `capitan kill --signal KILL`\n    capitan kill --signal KILL\n\n##### `rm`\t\t\nRemove stopped containers\n    \n    capitan rm\n    # Further arguments passed through to docker, example `capitan rm -f`\n    capitan rm -fv\n    \n### Non invasive commands\n    \n##### `ps`\nShow container status\n    \n    - Further arguments passed through to docker, example `capitan ps -a`\n\n##### `ip`\nShow container ip addresses\n\n##### `logs`\nFollow container logs\n\n##### `pull`\nPull images for all containers\n\n##### `build`\nBuild any containers with 'build' flag set (WIP)\n\n\n## Configuration\n\n     \n### Global options\n\n     --cmd, -c \"./capitan.cfg.sh\"\tCommand used to obtain config\n     --debug, -d\t\t\t\t    Print extra log messages\n     --dry-run, --dry\t\t\t    Preview outcome, no changes will be made\n     --filter, -f \t\t            Filter to run action on a specific container only\n     --help, -h\t\t\t\t        Show help\n     --version, -v\t\t\t        Print the version\n\n### Config file/output\n\nService config is read from stdout of the command defined with `--cmd` .\n\n`capitan` by default runs the command `./capitan.cfg.sh` in the current directory to get the config. This can be customized with `--cmd|-c` flag.\n\n    capitan --cmd ./someotherexecutable \u003csome action\u003e\n\nYou could use any command which generates a valid config. It doesn't have to be a bash script like in the example or default.\n\n### Filtering\n\nA single service type can specified for an action by using the `--filter|-f` flag. So if your conf looked like this:\n\n    ...\n    fooapp hostname blah\n    ...\n    \nYou could filter any command to run on just that service type by doing:\n\n    capitan --filter fooapp \u003csome action\u003e\n\n#### Global options\n\n##### `global project`\nThe project name, defaults to current working directory\n\n##### `global project_sep`\nString to use to create container name from `project` and name specified in config\n\n##### `global blue_green [true/false]`\nString to deploy using blue/green handover. Defaults to false. This can be turned on/off per container with\n\n    CONTAINER_NAME blue-green [true/false]\n    \n#### `global hook [hook name] [hook command]`\nAllows for a custom shell command to be evaluated once at the following points:\n\n- Before/After up (`before.up`, `after.up`)\n    - This occurs during the `up` command\n- Before/After Start (`before.start`, `after.start`)\n    - This will occur in the `start` command\n- Before/After Stop (`before.stop`, `after.stop`)\n    - This will occur in the `stop` command\n- Before/After Kill (`before.kill`, `after.kill`)\n    - This will occur in the `kill` command\n- Before/After Rm (`before.rm`, `after.rm`)\n    - This will occur in the `rm` command\n\n#### Container Options\n\nThe output format must be:\n\n    CONTAINER_NAME COMMAND [ARGS...]\n \nAll commands are passed through to docker cli as `--COMMAND` EXCEPT the following:\n\n#### `build`\nThis allows a path to be given for a dockerfile. Note, it will attempt to build every time. Use `build-args` and pass `--no-cache` to force a full clean build each time.\n\n#### `build-args`\nAny further arguments that need to be passed when building.\n\n#### `hook [hook name] [hook command]`\nAllows for a custom shell command to be evaluated at the following points **for each container**\n\n- Before/After Run (`before.run`, `after.run`)\n    - This occurs during the `up` command\n- Before/After Start (`before.start`, `after.start`)\n    - This will occur in the `up`, `start` and `restart` command\n- Before/After Stop (`before.stop`, `after.stop`)\n    - This will occur in the `stop` command only\n- Before/After Kill (`before.kill`, `after.kill`)\n    - This will occur in the `kill` command only\n- Before/After Rm (`before.rm`, `after.rm`)\n    - This will occur in the `up` and `rm` command\n       \n*NOTE* hooks do not conform exactly to each command. Example: an `up` command may `rm` and then `run` a container OR just `start` a stopped container.\n\n#### `scale`\nNumber of instances of the container to run. Default is 1.\n\nNOTE: this is untested with links ( I don't use links )\n\n#### `link`\nAn attempt to resolve a link to the first instance of a container is made. Otherwise the unresolved name is used.\n\nWARNING: When scaling, if the link resolves to a container defined in capitan's config, it will always resolve to the first instance.\nFor example: `app link mycontainer:some-alias` will always resolve to `\u003cproject\u003e_mycontainer_1`\n\n#### `rm`\n\nBy default capitan runs all commands with `-d`. This flag makes capitan run the command with `-rm` instead.\n\nWARNING: This feature is experimental and may result in unexpected failures. A more predictable way is to leverage `docker wait` along with a dynamic label.\nFor example:\n\n    mycontainer label $(date +%s)\n    mycontainer hook after.run docker wait \\$CAPITAN_CONTAINER_NAME\n\n#### `volumes-from`\n\nAn attempt to resolve a volume-from arg to the first instance of a container is made. Otherwise the unresolved name is used.\n\nWARNING: When scaling, if the container name resolves to a container defined in capitan's config, it will always resolve to the first instance.\nFor example: `app volumes-from mycontainer` will always resolve to `\u003cproject\u003e_mycontainer_1`\n\n### Environment Variables \n\nThe following environment variables are available when creating the containers and when running **container hooks**\n\n    # container name\n    CAPITAN_CONTAINER_NAME\n    # container type \n    CAPITAN_CONTAINER_SERVICE_TYPE\n    # instance of this type,eg if you have scale = 5 then each container will have their own instance number from 1 -\u003e 5\n    CAPITAN_CONTAINER_INSTANCE_NUMBER\n    # the project name\n    CAPITAN_PROJECT_NAME\n    \nThe following environment variables are available to all **hook** scripts\n\n    CAPITAN_PROJECT_NAME\n    CAPITAN_HOOK_NAME\n    \n\nFor example, following `capitan.cfg.sh`\n\n    #!/bin/bash\n\n    cat \u003c\u003cEOF\n    global project test\n\n    mysql name mymysql\n    mysql label containerName=\\$CAPITAN_CONTAINER_NAME\n    mysql label containerServiceName=\\$CAPITAN_CONTAINER_SERVICE_NAME\n    mysql label containerInstanceNumber=\\$CAPITAN_CONTAINER_INSTANCE_NUMBER\n    mysql label projectName=\\$CAPITAN_PROJECT_NAME\n    mysql hook after.run echo \"hook: \\$CAPITAN_HOOK_NAME: ran \\$CAPITAN_CONTAINER_NAME in project \\$CAPITAN_PROJECT_NAME\"\n    EOF\n\nWould result in the following run command:\n\n    docker run -d --name test_mysql_1 \n        --label containerName=test_mysql_1 \n        --label containerServiceName=mysql\n        --label containerInstanceNumber=1\n        --label projectName=test\n\nAnd the following hook ouput\n\n    Running test_mysql_1\n    34e7fffb937c3154c2a963ee605c7958404aa5d80519db4ef3d2a80a06974021\n    hook: after.run: ran test_mysql_1 in project test\n\nNote that the `$` must be escaped if using HEREDOC or double quotes in bash.\n\n\n### Example Config\n\nCheck out [dev-stack](https://github.com/byrnedo/dev-stack) for an example. \nClone it and just run `capitan --dry up`.\n\nOr check out the `./example` dir.\n\nAlso, here's something to whet your appetite:\n    \n    #!/bin/bash\n    PREFIX=dev\n    \n    cat \u003c\u003cEOF\n    #\n    # General redis container\n    #\n    redis image redis:latest\n    redis hostname ${PREFIX}_redis\n    redis publish 6379\n    redis hook after.run echo \"look everyone, I ran \\$CAPITAN_CONTAINER_NAME\" \u0026\u0026 sleep 3\n    redis hook after.start sleep 3\n    \n    #\n    # General mongodb container\n    #\n    mongo image mongo:latest\n    mongo command mongod --smallfiles\n    mongo hostname ${PREFIX}_mongo\n    mongo publish 27017\n    \n    #\n    # My app\n    #\n    app build ./\n    app publish 80\n    app link redis\n    app link mongo:mongodb\n    EOF\n\n## Roadmap\n\n1. Tests\n2. More efficient `up` logic\n3. Helpful aliases in shell env.\n4. More flexible `build` command\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyrnedo%2Fcapitan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbyrnedo%2Fcapitan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbyrnedo%2Fcapitan/lists"}