{"id":17901638,"url":"https://github.com/steveb/paunch","last_synced_at":"2025-04-03T05:26:48.197Z","repository":{"id":66670029,"uuid":"86412349","full_name":"steveb/paunch","owner":"steveb","description":"Utility to launch and manage containers using YAML based configuration data","archived":false,"fork":false,"pushed_at":"2017-04-27T04:37:35.000Z","size":43,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-08T19:34:56.441Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/steveb.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":"CONTRIBUTING.rst","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":"2017-03-28T03:47:18.000Z","updated_at":"2017-11-02T15:49:10.000Z","dependencies_parsed_at":"2023-02-23T10:00:48.054Z","dependency_job_id":null,"html_url":"https://github.com/steveb/paunch","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveb%2Fpaunch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveb%2Fpaunch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveb%2Fpaunch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/steveb%2Fpaunch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/steveb","download_url":"https://codeload.github.com/steveb/paunch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246941920,"owners_count":20858406,"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-10-28T16:02:57.514Z","updated_at":"2025-04-03T05:26:48.172Z","avatar_url":"https://github.com/steveb.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"===============================\npaunch\n===============================\n\nUtility to launch and manage containers using YAML based configuration data\n\n* Free software: Apache license\n* Documentation: https://docs.openstack.org/developer/paunch\n* Source: http://git.openstack.org/cgit/openstack/paunch\n* Bugs: http://bugs.launchpad.net/paunch\n\nFeatures\n--------\n\n* Single host only, operations are performed via the docker client on the\n  currently configured docker service.\n* Zero external state, only labels on running containers are used when\n  determining which containers an operation will perform on.\n* Single threaded and blocking, containers which are not configured to detach\n  will halt further configuration until they exit.\n* Co-exists with other container configuration tools. Only containers created\n  by paunch will be modified by paunch. Unique container names are assigned if\n  the desired name is taken, and containers are renamed when the desired name\n  becomes available.\n* Accessable via the ``paunch`` command line utility, or by importing python\n  package ``paunch``.\n\nRunning Paunch Commands\n-----------------------\n\nThe only state that paunch is aware of is the labels that it sets on running\ncontainers, so it is up to the user to keep track of what paunch configs\n*should* be running so that others can be deleted on cleanup. For these\nexamples we're going to store that state in a simple text file:\n\n::\n\n    $ touch paunch-state.txt\n\nWe'll start of by deleting any containers that were started by previous calls\nto ``paunch apply``:\n\n::\n\n    $ paunch --verbose cleanup $(cat paunch-state.txt)\n\nNext we'll apply a simple hello-world config found in\n``examples/hello-world.yml`` which contains the following:\n\n::\n\n    hello:\n      image: hello-world\n      detach: false\n\nApplied by running:\n\n::\n\n    $ paunch --verbose apply --file examples/hello-world.yml --config-id hi\n    $ echo hi \u003e\u003e paunch-state.txt\n\nA container called ``hello`` will be created, print a Hello World message, then\nexit. You can confirm that it still exists by running ``docker ps -a``.\n\nNow lets try running the exact same ``paunch apply`` command:\n\n::\n\n    $ paunch --verbose apply --file examples/hello-world.yml --config-id hi\n\nThis will fail with an error because there already exists a container labeled\nwith ``\"config_id\": \"hi\"``. **WARNING TODO NOT IMPLEMENTED YET**\n\nLets try again with a unique --config-id:\n\n::\n\n    $ paunch --verbose apply --file examples/hello-world.yml --config-id hi-again\n    $ echo hi-again \u003e\u003e paunch-state.txt\n\nDoing a ``docker ps -a`` now will show that there are now 2 containers, one\ncalled ``hello`` and the other called ``hello-(random suffix)``. Lets delete the\none associated with the ``hi`` config-id:\n\n::\n\n    $ cat paunch-state.txt\n    $ echo hi-again \u003e paunch-state.txt\n    $ cat paunch-state.txt\n    $ paunch --verbose cleanup $(cat paunch-state.txt)\n\nDoing a ``docker ps -a`` will show that the original ``hello`` container has been\ndeleted and ``hello-(random suffix)`` has been renamed to ``hello``\n\nGenerally ``paunch cleanup`` will be run first to delete containers for configs\nthat are no longer apply. Then a series of ``paunch apply`` commands can be run.\nIf these ``apply`` calls are part of a live upgrade where a mixture of old and\nnew containers are left running, the upgrade can be completed in the next run\nto ``paunch cleanup`` with the updated list of config-id state.\n\nPaunch can also be used as a library by other tools. By default running the\n``paunch`` command won't affect these other containers due to the different ``managed_by``\nlabel being set on those containers. For example if you wanted to run paunch\ncommands masquerading as the\n`heat-agents \u003chttp://git.openstack.org/cgit/openstack/heat-agents/tree/\u003e`_\n`docker-cmd hook \u003chttp://git.openstack.org/cgit/openstack/heat-agents/tree/heat-config-docker-cmd\u003e`_\nthen you can run:\n\n::\n\n  paunch --verbose apply --file examples/hello-world.yml --config-id hi --managed-by docker-cmd\n\nThis will result in a ``hello`` container being run, which will be deleted the\nnext time the ``docker-cmd`` hook does its own ``cleanup`` run since it won't\nbe aware of a ``config_id`` called ``hi``.\n\nConfiguration Format\n--------------------\n\nThe current format is loosely based on a subset of the `docker-compose v1\nformat \u003chttps://docs.docker.com/compose/compose-file/compose-file-v1/\u003e`_ with\nmodifications. The intention is for the format to evolve to faithfully\nimplement existing formats such as the\n`Kubernetes Pod format \u003chttps://kubernetes.io/docs/concepts/workloads/pods/pod/\u003e`_.\n\nThe top-level of the YAML format is a dict where the keys (generally)\ncorrespond to the name of the container to be created.  The following config\ncreates 2 containers called ``hello1`` and ``hello2``:\n\n::\n\n    hello1:\n      image: hello-world\n    hello2:\n      image: hello-world\n\nThe values are a dict which specifies the arguments that are used when the\ncontainer is launched. Supported keys which comply with the docker-compose v1\nformat are as follows:\n\ncommand:\n  String or list. Overrides the default command.\n\ndetach:\n  Boolean, defaults to true. If true the container is run in the background. If\n  false then paunch will block until the container has exited.\n\nenvironment:\n  List of the format ['KEY1=value1', 'KEY2=value2']. Sets environment variables\n  that are available to the process launched in the container.\n\nenv_file:\n  List of file paths containing line delimited environment variables.\n\nimage:\n  String, mandatory. Specify the image to start the container from. Can either\n  be a repository/tag or a partial image ID.\n\nnet:\n  String. Set the network mode for the container.\n\npid:\n  String. Set the PID mode for the container.\n\nprivileged:\n  Boolean, defaults to false. If true, give extended privileges to this container.\n\nrestart:\n  String. Restart policy to apply when a container exits.\n\nuser:\n  String. Sets the username or UID used and optionally the groupname or GID for\n  the specified command.\n\nvolumes:\n  List of strings. Specify the bind mount for this container.\n\nvolumes_from:\n  List of strings. Mount volumes from the specified container(s).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveb%2Fpaunch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsteveb%2Fpaunch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsteveb%2Fpaunch/lists"}