{"id":22071777,"url":"https://github.com/mhutter/ansible-docker-systemd-service","last_synced_at":"2025-04-07T09:20:42.284Z","repository":{"id":42461321,"uuid":"101399942","full_name":"mhutter/ansible-docker-systemd-service","owner":"mhutter","description":"Ansible role for creating Systemd services for docker containers","archived":false,"fork":false,"pushed_at":"2024-10-15T20:14:37.000Z","size":119,"stargazers_count":48,"open_issues_count":9,"forks_count":30,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-17T06:39:26.339Z","etag":null,"topics":["ansible","docker","systemd"],"latest_commit_sha":null,"homepage":"https://galaxy.ansible.com/mhutter/docker-systemd-service","language":"Jinja","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/mhutter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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-08-25T12:05:21.000Z","updated_at":"2024-08-27T23:17:12.000Z","dependencies_parsed_at":"2024-03-27T21:23:47.788Z","dependency_job_id":"dc18529d-8efd-4416-bf5d-e156b0ada7db","html_url":"https://github.com/mhutter/ansible-docker-systemd-service","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhutter%2Fansible-docker-systemd-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhutter%2Fansible-docker-systemd-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhutter%2Fansible-docker-systemd-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mhutter%2Fansible-docker-systemd-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mhutter","download_url":"https://codeload.github.com/mhutter/ansible-docker-systemd-service/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622983,"owners_count":20968575,"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":["ansible","docker","systemd"],"created_at":"2024-11-30T20:34:04.581Z","updated_at":"2025-04-07T09:20:42.254Z","avatar_url":"https://github.com/mhutter.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker role `mhutter.docker-systemd-service`\n\nGeneric role for creating systemd services to manage docker containers.\n\n## Example\n\nExample of a Systemd unit for your app \"myapp\" that links to an already existing container \"mysql\":\n\n```yaml\n- name: Start WebApp\n  include_role:\n    name: mhutter.docker-systemd-service\n  vars:\n    container_name: myapp\n    container_image: myapp:latest\n    container_links: [\"mysql\"]\n    container_volumes:\n      - \"/data/uploads:/data/uploads\"\n    container_ports:\n      - \"3000:3000\"\n    container_hosts:\n      - \"host.docker.internal:host-gateway\"\n    container_env:\n      MYSQL_ROOT_PASSWORD: \"{{ mysql_root_pw }}\"\n    container_labels:\n      - \"traefik.enable=true\"\n```\n\nThis will create:\n\n- A file containing the env vars (either `/etc/sysconfig/myapp` or `/etc/default/myapp`).\n- A systemd unit which starts and stops the container. The unit will be called `\u003cname\u003e_container.service` to avoid name clashes.\n\n### Role variables\n\n- `container_name` (**required**) - name of the container\n\n#### Docker container specifics\n\n- `container_image` (**required**) - Docker image the service uses\n- `container_args` - arbitrary list of arguments to the `docker run` command as a string\n- `container_cmd` (default: _[]_) - optional list of commands to the container run command (the part after the image name)\n- `container_env` - key/value pairs of ENV vars that need to be present\n- `container_volumes` (default: _[]_) - List of `-v` arguments\n- `container_host_network` (default: _false_) - Whether the host network should be used\n- `container_ports` (default: _[]_) - List of `-p` arguments\n- `container_hosts` (default: _[]_) - List of `--add-host` arguments\n- `container_links` (default: _[]_) - List of `--link` arguments\n- `container_labels` (default: _[]_) - List of `-l` arguments\n- `container_docker_pull` (default: _yes_) - whether the docker image should be pulled\n- `container_docker_pull_force_source` (default: _yes_) - whether the docker image pull should be executed at every time (see [`docker_image.force_source`](https://docs.ansible.com/ansible/latest/collections/community/docker/docker_image_module.html#parameter-force_source))\n- `container_cap_add` (default _[]_) - List of capabilities to add\n- `container_cap_drop` (default _{}_) - List of capabilities to drop\n- `container_network` (default _\"\"_) - [Network settings](https://docs.docker.com/engine/reference/run/#network-settings)\n- `container_user` (default _\"\"_) - [User settings](https://docs.docker.com/engine/reference/run/#user)\n- `container_hostname` (default _\"\"_) - Container host name: `--hostname` flag\n- `container_devices` (default _[]_) - List of devices to add\n- `container_privileged` (default _false_) - Whether the container should be privileged\n- `container_start_post` - Optional command to be run by systemd after the container has started\n\n#### Systemd service specifics\n\n- `service_enabled` (default: _yes_) - whether the service should be enabled\n- `service_masked` (default: _no_) - whether the service should be masked\n- `service_state` (default: _started_) - state the service should be in - set to\n  `absent` to remove the service.\n- `service_restart` (default: _yes_) - whether the service should be restarted on changes\n- `service_name` (default: `\u003ccontainer_name\u003e_container`) - name of the systemd service\n- `service_systemd_options` (default: _[]_) - Extra options to include in systemd service file\n- `service_systemd_unit_options`: (default `{\"After\": \"docker.service\", \"PartOf\": \"docker.service\", \"Requires\": \"docker.service\"}`), key/value defining the content of the `[Unit]` service section.\n\n## Installation\n\nThis role requires the [docker python module](https://pypi.org/project/docker/). Install it with `pip3 install docker` or `apt install python3-docker` (or drop the `3` for python 2.x).\n\nPut this in your `requirements.yml`:\n\n```yml\n- role: mhutter.docker-systemd-service\n```\n\nand run `ansible-galaxy install -r requirements.yml`.\n\n## Gotchas\n\n- When the unit or env file is changed, systemd gets reloaded but existing containers are NOT restarted.\n- Make sure to quote values for `container_ports`, `container_hosts`, `container_volumes` and so on, especially if they contain colons (`:`). Otherwise YAML will interpret them as hashes/maps and ansible will throw up.\n\n## About orchestrating Docker containers using systemd.\n\nThe concept behind this is to define `systemd` units for every docker container. This has some benefits:\n\n- `systemd` is a well-known interface\n- all services are controllable via the same tool (`systemctl`)\n- all logs are accessible via the same tool (`journalctl`)\n- dependencies can be defined\n- startup behaviour can be defined\n- by correctly defining the unit (see below), we can ensure we always have a clean container.\n\nHere is an example `myapp_container.service` unit file (about what's produced by above code):\n\n    [Unit]\n    # define dependencies\n    After=docker.service\n    PartOf=docker.service\n    Requires=docker.service\n\n    [Service]\n    # Load ENV vars from a file. Note that this env vars will only be\n    # accessible in the context of the Exec* commands, and not within the\n    # container itself. To make env-vars accessible within the Container, we use\n    # the `--env-file` flag for the `docker run` command.\n    EnvironmentFile=/etc/sysconfig/myapp\n\n    # Even though we explicitly run the container using the `--rm` flag, there\n    # may be leftover containers (eg. after a system-, docker- or app-crash).\n    # Starting a container with an existing name will always fail.\n\n    ExecStartPre=-/usr/bin/docker rm -f myapp\n\n    # actually run the container.\n    # `--name` to identify the container\n    # `--rm` ensure the container is removed after stopping\n    # `--env-file` make ENV vars accessible to app\n    # `--link mysql` link to a container named `mysql`. The DB will then be\n    #                accesible at `mysql:3306`\n    # `-v` mount `/data/uploads` into the container\n    # `-p 3000:3000` expose port 3000 on the network\n    ExecStart=/usr/bin/docker run --name myapp --rm --env-file /etc/sysconfig/myapp --link mysql -v /data/uploads:/data/uploads -p 3000:3000 registry.cust.net/myapp/myapp:latest\n    # note that there is no `--restart` parameter. This is because restarting\n    # is taken care of by `systemd`.\n\n    # Stop command.\n    ExecStop=/usr/bin/docker stop myapp\n\n    # Ensure log messages are correctly tagged in the system log.\n    SyslogIdentifier=myapp\n\n    # Auto-Restart the container after a crash.\n    Restart=always\n\n\n    [Install]\n    # make sure service is started after docker is up\n    WantedBy=docker.service\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhutter%2Fansible-docker-systemd-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmhutter%2Fansible-docker-systemd-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmhutter%2Fansible-docker-systemd-service/lists"}