{"id":14155241,"url":"https://github.com/caracolazuldev/d-composer","last_synced_at":"2025-08-06T01:30:46.256Z","repository":{"id":77036026,"uuid":"499555757","full_name":"caracolazuldev/d-composer","owner":"caracolazuldev","description":"A Gnu Make Makefile include to manage complex docker-compose definitions.","archived":false,"fork":false,"pushed_at":"2024-05-30T21:07:48.000Z","size":84,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-24T01:59:21.387Z","etag":null,"topics":["docker","docker-compose","make","makefile"],"latest_commit_sha":null,"homepage":"","language":"Makefile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/caracolazuldev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"Roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-03T15:11:07.000Z","updated_at":"2024-05-22T14:39:36.000Z","dependencies_parsed_at":"2024-03-28T08:09:58.152Z","dependency_job_id":"f093916a-d7de-44c3-8d7e-0ff03c16d71d","html_url":"https://github.com/caracolazuldev/d-composer","commit_stats":null,"previous_names":["caracolazuldev/d-composer"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caracolazuldev%2Fd-composer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caracolazuldev%2Fd-composer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caracolazuldev%2Fd-composer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/caracolazuldev%2Fd-composer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/caracolazuldev","download_url":"https://codeload.github.com/caracolazuldev/d-composer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215735785,"owners_count":15923388,"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":["docker","docker-compose","make","makefile"],"created_at":"2024-08-17T08:02:34.703Z","updated_at":"2024-08-17T08:04:55.482Z","avatar_url":"https://github.com/caracolazuldev.png","language":"Makefile","funding_links":[],"categories":["docker-compose"],"sub_categories":[],"readme":"\n# Decomposer\n\nWelcome to Decomposer, the Docker-Compose Configuration Manager. As a Makefile include, it easily integrates into your Makefile-based or shell-script build and deployment tools. \n\nThis Makefile facilitates dynamically generating `docker-compose.yml` files from reusable service declarations. You might want to do this to test your application on different deployment targets or environments without duplicating common service definitions. Or, more easily re-use service definitions from one project to the next. Other use-cases might be: having different stacks for development, unit testing, integration and QA testing, or generating production builds.\n\nTo generate a `docker-compose.yml` file and an `.env` file, decomposer looks in the environment variables, `STACK_SERVICES` and `ENV_INCLUDES`, to generate a list of file includes. You can easily switch between stacks using the `activate` and `deactivate` commands. You must first set the `STACK` environment variable to the name of the stack you want to activate. Using the stack name, additional files are automatically discovered and included in the `docker-compose.yml` and `.env` files.\n\nFor lazy typers, decomposer aliases `docker compose` commands. Rather than typing `docker compose` commands directly, you will use `make` followed by the docker-compose command you want to run, e.g. `make up`, `make down`, `make exec`, etc. See the [Aliases and Custom Commands](#aliases-and-custom-commands) section for additional commands not provided by `docker compose`.\n\nIn addition to wrapping `docker compose`, decomposer smooths-out some rough-edges in the `docker-compose` cli. For example, automatically passing the `--rm` flag to `docker compose run`, bringing up applications in detached mode by default, or cleanly removing a task by implicitly calling `docker-compose rm --force --stop`.\n\nThe command wrappers also facilitate extending your development environment with ad hoc commands in your main Makefile. For example, you can run `make TASK=shell` to run a shell in the active stack, or `make TASK=php8-apache RUN_CMD='php -i'` to run `php -i` in the PHP 8 Apache container.\n\nDecomposer need not be adopted by an entire team because it does not break classic `docker-compose` usage. For those team members that do not need to switch between stacks, you can commit fully-generated `docker-compose.yml` files to your repository, and they can use `docker-compose` as they always have.\n\nGain deeper insights into Decomposer on folder structure, environment variables, and configuration files:\n\n- see [docs/Orientation](docs/Orientation.md)\n\n## Installation\n\nMakefile global includes are typically installed in `/usr/local/include`. To install Decomposer as a global include, clone the repository and run `make install` with admin permissions. You can override the install location with `INSTALL_LOCATION`. But really, \"installation\" is just copying the `decomposer.mk` file to a location where you can include it in your top-level Makefile.\n\n## Decomposing Compose Definitions\n\nDocker Compose definitions are decomposed into smaller, modular files for better maintainability and flexibility. When you set the `STACK` environment variable and run `make activate`, a `docker-compose.yml` and a `.env` file are generated. The `docker/` directory contains service definitions in the form of docker-compose service declaration fragments, using `docker compose config` to unify the fragments.\n\nThe stack is defined by the `STACK_SERVICES` environment variable, each word will automatically have the `.yml` extension appended to it. The `docker-compose.yml` file is generated by pattern-matching on the stack-name in the project-root directory, any corresponding `.yml` files for each service declared in the stack, and any additional files specified in the `STACK_INCLUDES` environment variable. You can include any arbitrary file by adding it to the `STACK_INCLUDES` environment variable, as long as it is in the `docker/` directory.\n\nThen, each of your services in the `docker/` directory will start with a `service` stanza, and one service definition.\n```yaml\nservices:\n  \u003cmy-service\u003e:\n  image: \u003cmy-image\u003e\n    build:\n      args:\n        LOGIN_UID: ${LOGIN_UID:-1000}\n        LOGIN_GID: ${LOGIN_GID:-1000}\n        FROM_IMAGE: ${FROM_IMAGE:-php:8-apache}\n\t# ...\n```\n\nThis takes advantage of the fact that `docker compose` can take multiple configuration files, and compose them. Rather than passing a list of files on each invocation, we use the `config` command to pre-generate a single `docker-compose.yml` file. This is why you must `activate` a stack before running `docker compose` commands.\n\n The `.env` file is concatenated from files discovered by pattern-matching on the stack-name in the project-root directory, any corresponding `.env` files for each service declared in the stack, and any additional files specified in the `ENV_INCLUDES` environment variable.\n\n\n## Environment Variables\n\nThe Makefile utilizes the following environment variables:\n\n- `STACK`: Defines the active stack.\n- `STACK_SERVICES`: Specifies the list of services within the stack.\n- `ENV_INCLUDES`: Additional files used to generate the `.env` file.\n- `COMPOSER_PROJECT_NAME`: Determines the project's network name if you don't want to use the default.\n- `DK_CMP_OPTS`: Options passed to `docker-compose` commands.\n- `TASK`: Specifies a docker-compose service, used to run ad hoc commands.\n- `RUN_CMD`: Command to execute in the specified service.\n- `CMD_ARGS`: Additional options for `RUN_CMD`.\n\n## Examples\n\nHere are some common usage examples:\n\n- `STACK=lamp make up`: Bring up the LAMP stack.\n- `STACK=lamp TASK=shell make run`: Run a shell in the LAMP stack.\n- `make TASK=mysqld top`: View the top processes in the MySQL service.\n- `make config CMD_ARGS=--services`: Review the generated `docker-compose.yml`.\n- `make build TASK=php8-apache DK_CMP_OPTS='--no-cache'`: Build the PHP 8 Apache image with no cache.\n- `make exec TASK=php8-apache RUN_CMD='php -i'`: Execute `php -i` in the PHP 8 Apache container.\n- `make rund TASK=shell RUN_CMD='php' CMD_ARGS=\"-r 'phpinfo();'\"`: Run PHP with `phpinfo()` in the shell container.\n\n## Troubleshooting\n\nIf you are having trouble defining commands, you can set the environment variable `DEBUG` to be non-empty, and the Makefile will print the constructed command.\n\n## Aliases and Custom Commands\n\nAny `docker-compose` command can be run with `make` by prefixing the command with `make`. For example, `docker compose up` becomes `make up`. In addition to the `docker-compose` commands, the Makefile provides some additional commands:\n\n- `make services`: List the services in the active stack. Alias of `docker compose config --services`.\n- `make config`: Review the generated `docker-compose.yml` file. Alias of `docker compose config`.\n- `make up`: Bring up the active stack, and detach. Alias of `docker compose up -d`.\n- `make down`: Stop and remove the active stack. When a TASK is specified, alias of `docker-compose rm --force --stop`.\n- `make run`: Run a command in the specified service (`TASK`) and remove it when stopped. Alias of `docker compose run --rm`.\n- `make rund`: Like `run`, but runs detached (like in background). Alias of `docker compose run -d`.\n- `make orphans`: Remove orphaned containers. Alias of `docker compose down --remove-orphans`.\n\n\u003e **NOTE:** some newer `docker-compose` commands are not yet aliased. You can still run them with `make` by prefixing the compose command with `dkc-`, e.g. `make dkc-images`, or `make dkc-copy`.\n\n**Bonus for lazy-typers:** recommended aliases to add to your shell profile:\n``` sh\nalias dk='docker'\nalias dkc='docker compose'\nalias dki='docker image'\nalias dkl='docker ps -a --format '\\''table {{if .ID}}{{slice .ID 0 4}}{{end}}\\t{{.Names}}\\t{{if .Status}}{{slice .Status 0 2}}{{end}}\\t{{.Image}}\\t{{.Command}}'\\'''\nalias dkll='dkl --no-trunc'\nalias dkr='docker run --rm'\nalias dke='docker exec -it'\n```\n\n## Getting Started with Docker Compose\n\nIf you're new to Docker Compose and are not familiar with project names, networks, volumes, tasks, and common Docker Compose commands, see our [docs/Compose Quick-start](docs/Compose Quick-start.md) for some sign-posts to start your journey.\n\nFor more detailed explanations and references, feel free to explore Docker Compose documentation:\n\n- [Docker Compose Reference](https://docs.docker.com/compose/reference/envvars/)\n- [Compose File Reference](https://docs.docker.com/compose/compose-file/compose-file-v3/)\n- [Docker Compose Documentation](https://docs.docker.com/compose/reference/)\n\nEnjoy managing your Docker Compose configurations with ease using this Makefile!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaracolazuldev%2Fd-composer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcaracolazuldev%2Fd-composer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcaracolazuldev%2Fd-composer/lists"}