92 lines
16 KiB
Markdown
92 lines
16 KiB
Markdown
<!--
|
|
Ansible Roles for managing Auengun.net Infrastructure & Testing/Learning.
|
|
Source available at git.auengun.net/homelab/ansible-collection
|
|
Copyright (C) 2023 GregoryDosh
|
|
|
|
This program is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU Affero General Public License as
|
|
published by the Free Software Foundation, either version 3 of the
|
|
License, or (at your option) any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU Affero General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Affero General Public License
|
|
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
|
|
|
SPDX-License-Identifier: AGPL-3.0-or-later
|
|
SPDX-FileCopyrightText: 2023 GregoryDosh
|
|
-->
|
|
|
|
# Ansible Role `auengun.homelab.dcaass`
|
|
|
|
DCaaSS - Docker Compose as a SystemD Service
|
|
|
|
This role creates a [`systemd`](https://www.man7.org/linux/man-pages/man5/systemd.service.5.html) service wrapper around a `docker-compose.yml` file.
|
|
|
|
## Installation
|
|
|
|
Read the [Homelab Collection README.md](../../README.md) for installation instructions.
|
|
|
|
### Ansible Configuration
|
|
|
|
This Ansible role uses the following [`vars`](https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_variables.html).
|
|
|
|
| Ansible `vars:` Name | Description | Default |
|
|
| -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `DCAASS_CONFIG_PATH` | Path to store `.env` and `docker-compose.yml` files. | `/dcaass/` |
|
|
| `DCAASS_CONFIG_USER_NAME` | User/owner for `DCAASS_CONFIG_PATH` config directory. | `dcaass` |
|
|
| `DCAASS_CONFIG_GROUP_NAME` | Group name for `DCAASS_CONFIG_PATH` config directory. | `dcaass` |
|
|
| `DCAASS_CONFIG_DIR_MODE` | Permissions for `DCAASS_CONFIG_PATH` config directory. | `0750` |
|
|
| `DCAASS_CONFIG_FILE_MODE` | Permissions for `.env` and `docker-compose.yml` files | `0640` |
|
|
| `DCAASS_ENV_FILE_NAME` | Change the [default `.env`](./templates/env.j2) file name. | `.env` |
|
|
| `DCAASS_ENV_EXTRA_CONFIG` | Any additional user defined environmental variables can be placed here. | |
|
|
| `DCAASS_EXTRA_CONFIG_DIRS` | Additional user defined directories can be specified here, they'll be templated into place with DCAASS user/group permissions. | `[]` |
|
|
| `DCAASS_EXTRA_CONFIG_FILES` | Additional user defined files can be specified here, they'll be templated into place with DCAASS user/group permissions. Changes to files will prompt DCaaSS reload. | `[]` |
|
|
| `DCAASS_SERVICE_ANSIBLE_ALLOW_RESTART` | Allow Ansible to (re)start the service on `.env` or `docker-compose.yml` changes. | `true` |
|
|
| `DCAASS_SERVICE_ANSIBLE_RESTART_ASYNC` | Allow Ansible to restart the service asynchronously. See `defaults.yml` for additional params. | `false` |
|
|
| `DCAASS_SERVICE_ANSIBLE_RELOAD_TYPE` | What [Ansible SystemD State](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/systemd_service_module.html#parameter-state) to use when restarting DCaaSS. | `restarted` |
|
|
| `DCAASS_SERVICE_NAME` | Name of systemd service. (e.g. `systemctl status dcass` & `journalctl -eu dcass`) | `dcaass` |
|
|
| `DCAASS_SERVICE_RESTART_POLICY` | Restart policy if the systemd service fails (could be docker/user/system/etc.). | `on-failure` |
|
|
| `DCAASS_SERVICE_RESTART_SEC` | Time between restart attempts. | `30` |
|
|
| `DCAASS_SERVICE_EXTRA_CONFIG_UNIT` | Additional `[Unit]` service parameters can be placed here. | |
|
|
| `DCAASS_SERVICE_EXTRA_CONFIG_SERVICE` | Additional `[Service]` service parameters can be placed here. | |
|
|
| `DCAASS_SERVICE_EXTRA_CONFIG_INSTALL` | Additional `[Install]` service parameters can be placed here. | |
|
|
| `DCAASS_SERVICE_USER_NAME` | User/owner for the systemd `.service` file. | `root` |
|
|
| `DCAASS_SERVICE_GROUP_NAME` | Group name for the systemd `.service` file. | `root` |
|
|
| `DCAASS_DOCKER_DAEMON_ALLOW_RESTART` | Allow Ansible to restart the docker service on `/etc/docker/daemon.json` changes. | `true` |
|
|
| `DCAASS_DOCKER_PRIVATE_MIRROR_INSTALL` | Whether to install the Docker internal private registry/mirror (will restart docker service on change). | `true` |
|
|
| `DCAASS_DOCKER_PRUNE_SERVICE_INSTALL` | Whether to install the Docker Prune service/timer when installing the DCaaSS service. | `true` |
|
|
| `DCAASS_DOCKER_PRUNE_SERVICE_NAME` | Name to use for the Docker Prune service/timer. | `{{ DCAASS_SERVICE_NAME }}_prune` |
|
|
| `DCAASS_DOCKER_PRUNE_SERVICE_USER_NAME` | User/owner for the Docker Prune systemd `.service`/`.timer` file. | `{{ DCAASS_SERVICE_USER_NAME }}` |
|
|
| `DCAASS_DOCKER_PRUNE_SERVICE_GROUP_NAME` | Group name for the Docker Prune systemd `.service`/`.timer` file. | `{{ DCAASS_SERVICE_GROUP_NAME }}` |
|
|
| `DCAASS_DOCKER_COMPOSE_PATH` | The `docker-compose.yml` file to be Jinja2 templated into the config path. Required by end users. | `templates/docker-compose.yml` |
|
|
| `DCAASS_DOCKER_COMPOSE_BASE_TEMPLATE` | The `docker-compose.yml` after template interpolation. Generally not needed to be tweaked. | `{{ lookup('template', DCAASS_DOCKER_COMPOSE_PATH) }}` |
|
|
| `DCAASS_DOCKER_COMPOSE_YAML_OVERRIDES` | Any additional `yaml` formatted overrides can go here. They'll extend/override existing `docker-compose.yml` options. | `{}` |
|
|
| `DCAASS_DOCKER_COMPOSE` | The combination of the base template and the user overrides as a string. Generally not needed to be tweaked. | `{{ DCAASS_DOCKER_COMPOSE_BASE_TEMPLATE \| from_yaml \| combine(((DCAASS_DOCKER_COMPOSE_YAML_OVERRIDES \| from_yaml) if (DCAASS_DOCKER_COMPOSE_YAML_OVERRIDES \| from_yaml) is mapping else {}), recursive=True) }}` |
|
|
| `DCAASS_DOCKER_COMPOSE_PULL_INITIAL_IMAGES` | Include a step during playbook to pull images in the `docker-compose.yml` | `true` |
|
|
| `DCAASS_DOCKER_COMPOSE_BUILD_INITIAL_IMAGES` | Include a step during playbook to build images in the `docker-compose.yml` | `false` |
|
|
|
|
## Examples
|
|
|
|
```yaml
|
|
- name: DCaaSS Example Overrides
|
|
hosts: servers
|
|
tags:
|
|
- dcaass
|
|
tasks:
|
|
- ansible.builtin.include_role:
|
|
name: auengun.homelab.dcaass
|
|
vars:
|
|
DCAASS_DOCKER_COMPOSE_PATH: "some/path/docker-compose.dev.yml.j2"
|
|
DCAASS_DOCKER_COMPOSE_YAML_OVERRIDES:
|
|
services:
|
|
alpine:
|
|
image: alpine:latest
|
|
command: echo 'hello'
|
|
DCAASS_ENV_EXTRA_CONFIG: |
|
|
ENV=dev
|
|
APP_VERSION=1.2.3
|
|
```
|