{"id":21334325,"url":"https://github.com/marcinhlybin/docker-env","last_synced_at":"2025-07-12T11:30:43.861Z","repository":{"id":257792512,"uuid":"838925484","full_name":"marcinhlybin/docker-env","owner":"marcinhlybin","description":"Per branch docker compose environment manager","archived":false,"fork":false,"pushed_at":"2024-10-31T16:01:50.000Z","size":118,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-11-15T00:14:01.611Z","etag":null,"topics":["branch","developer-tools","development-environment","devops-tools","docker","docker-compose","git"],"latest_commit_sha":null,"homepage":"","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/marcinhlybin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-08-06T15:56:55.000Z","updated_at":"2024-10-31T15:58:05.000Z","dependencies_parsed_at":"2024-09-24T06:24:02.083Z","dependency_job_id":"5fc7dce4-2c7f-457f-82bb-0bb905b3f780","html_url":"https://github.com/marcinhlybin/docker-env","commit_stats":null,"previous_names":["marcinhlybin/docker-env"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcinhlybin%2Fdocker-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcinhlybin%2Fdocker-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcinhlybin%2Fdocker-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcinhlybin%2Fdocker-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcinhlybin","download_url":"https://codeload.github.com/marcinhlybin/docker-env/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225815807,"owners_count":17528449,"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":["branch","developer-tools","development-environment","devops-tools","docker","docker-compose","git"],"created_at":"2024-11-21T23:20:16.696Z","updated_at":"2025-07-12T11:30:43.835Z","avatar_url":"https://github.com/marcinhlybin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Docker environments manager\n\n**docker-env** allows developers to create, manage and switch between isolated docker projects (or stacks) per git branch within a single repository. It simplifies working with docker-compose and supports hooks for customization and sidecar containers for optional services.\n\n![demo](https://github.com/user-attachments/assets/52289faf-8d40-42dc-8670-b5260ccfedc6)\n\n## Why\n\nManaging Docker environments across multiple branches or projects can be cumbersome, especially when dealing with complex application stacks that include databases, caches, and other services.\n\nThe goal of docker-env is to streamline this process by automating the creation and management of docker-compose environments. Each environment is tied to a Git branch, allowing developers to easily switch between isolated stacks without affecting their work in progress. This ensures that data, services, and application states are preserved across branches and projects.\n\nIn short, docker-env abstracts common docker-compose tasks, allowing you to focus on development while it handles the heavy lifting.\n\n## Key features\n\n- Project (or stack) per branch. Create a new environment automatically when switching branches.\n- Repository isolation: Prefix project by repository name, ensuring no conflicts between different repositories.\n- Sidecar containers: Optional services, like admin tools or background jobs, can be started as needed without starting by default.\n- Hooks: Customize pre-start, post-start, and post-stop behaviors with hooks.\n\n## Installing\n\nOn MacOS use Homebrew to install:\n\n```\nbrew install marcinhlybin/tap/docker-env\n```\n\nOn Linux see building or download binary from releases.\n\n## Building\n\nRun `make` to build a binary to the current directory.\n\n```\nbrew install go\nmake test\nmake install\n```\n\nInstalls into `/usr/local/bin`. Sudo password required.\n\n## Usage\n\n```\nNAME:\n   docker-env - Docker environments manager\n\nUSAGE:\n   docker-env [global options] command [command options]\n\nVERSION:\n   2.0.0\n\nDESCRIPTION:\n   All commands must run in the git repository directory of the project.\n   If environment name is not specified current branch name is used.\n\nCOMMANDS:\n   start, s, up                Start docker containers\n   stop, ss, down              Stop docker containers\n   restart, r, reboot          Restart docker containers\n   remove, rm, delete          Remove docker containers\n   ls, list, l, ll             List projects, 'll' to show containers.\n   reset, cleanup              Removes all projects\n   build, b                    Build docker images\n   info, config, show          Show configuration\n   terminal, term, shell, ssh  Run terminal\n   code, open                  Open code editor\n   version, v                  Show version\n   logs, log                   Show container logs\n   help, h                     Shows a list of commands or help for one command\n\nGLOBAL OPTIONS:\n   --config value, -c value  config file path\n   --debug, -d               enable debug mode (default: false)\n   --quiet, -q               disable info messages (default: false)\n   --quieter, --qq           disable docker output (default: false)\n   --help, -h                show help\n   --version, -v             show version string, alias for 'version --short' (default: false)\n```\n\nStart command usage:\n\n```\nNAME:\n   docker-env start - Start docker containers\n\nUSAGE:\n   docker-env start [command options]\n\nDESCRIPTION:\n   Start docker containers.\n   If project name is not specified, master branch is used.\n   If project does not exist it will be created.\n\nOPTIONS:\n   --project value, -p value    set a project name\n   --branch, -b                 use current git branch as project name (default: false)\n   --service value, -s value    start a single service\n   --recreate, -r               recreate the containers (default: false)\n   --update, -u                 update the images and recreate the containers (default: false)\n   --no-hooks, --without-hooks  do not run pre/post start hooks (default: false)\n   --help, -h                   show help\n```\n\n## Sample commands\n\n```\n# Create new environment with default git branch (master)\ndocker-env start\n\n# Create branch based environment\ndocker-env start -b\n\n# Create new environment with custom name\ndocker-env start -p db-fix\n\n# Restart environment\ndocker-env restart -p db-fix\n\n# Restart a single container\ndocker-env restart -p db-fix -s app\n\n# Restart a single container from active environment\ndocker-env restart -s postgresql\n\n# Recreate all containers\ndocker-env start -r\n\n# Recreate a single container\ndocker-env start -s postgresql -r\n\n# Update all images and recreate containers\ndocker-env start -u\n\n# Update image of a single container and recreate\ndocker-env start -s app -u\n\n# Cleanup environments and images\ndocker-env reset --hard\n\n# Run shell\ndocker-env shell\n\n# Run command in a container\ndocker-env shell -s postgresql createdb -U postgres mydb\n\n# Show container logs with follow option\ndocker-env logs -s nginx -f\n```\n\n## Docker compose\n\n### Requirements\n\nContainer name in service definition **must be prefixed** with `$COMPOSE_PROJECT_NAME-`:\n\n```\nservices:\n  app:\n    container_name: $COMPOSE_PROJECT_NAME-app\n    image: 1234567890.dkr.ecr.eu-central-1.amazonaws.com/my-app\n    ports:\n    [...]\n```\n\n### Extending docker compose configuration\n\nBy default **docker-env** uses `docker-compose.yml` for service definition. The configuration can be extended with `docker-compose.override.yml`.\n\n### Variables\n\nDocker compose configuration can be manipulated with environmental variables stored in `env_files` defined in `./docker-env/config.yml` file. Usually it is local `.env` file which should be added to `.gitignore` as it may contain secrets like `GITHUB_TOKEN` or AWS credentials.\n\nBy setting `required_vars` option in `./docker-env/config.yml` you can check during runtime if variables can be found.\n\n### Sidecar containers\n\nBy default **docker-env** uses `app` profile to start contianers. Profile `sidecar` is used to specify containers that are not started by default and can be started later individually using `docker-env start -s` command.\n\nProfile names are defined in the configuration file:\n\n```\ncompose_default_profile: app\ncompose_sidecar_profile: sidecar\n```\n\n## Configuration\n\nEach repository should define its own configuration file located in `./docker-env/config.yml`. It is recommended to commit config file to the repository. It can be extended locally with `./docker-env/config.override.yml` (add it to `.gitignore`). For example it can be used to replace registry images and build own using `docker-env build` command.\n\n```\n### Docker-env configuration file\n\n# Docker compose projects and their containers will be prefixed with this name\n# Only alphanumeric characters and underscores are allowed, no hyphens\n# Make sure to name service names in the docker-compose.yml file\n# using \"$COMPOSE_PROJECT_NAME-\" prefix\ncompose_project_name: docker_env\n\n# Docker compose configuration\ncompose_file: docker-compose.yml\ncompose_file_override: docker-compose.override.yml\n\n# Profiles are used to distinguish between default startup services\n# and services that are only started when explicitly requested by the user\n# so called sidecar services\ncompose_default_profile: app\ncompose_sidecar_profile: sidecar\n\n# Git options\ngit_default_branch: master\n\n# Debug options\nshow_executed_commands: true\n\n# Env files to load environmental variables used in the docker-compose.yml file\n# for substitution in the services section\nenv_files:\n  - .env\n\n# Check for following environment variables in env files\nrequired_vars:\n  - GITHUB_USER\n  - GITHUB_TOKEN\n  - AWS_PROFILE\n  - AWS_MFA_SERIAL\n\n# AWS registry\naws_login: false\naws_region: eu-central-1\naws_repository: 1234567890.dkr.ecr.eu-central-1.amazonaws.com\n\n# Use MFA (multi-factor authentication) for AWS login\n# Requires AWS_MFA_SERIAL environment variable to be set in the .env file\n# Sample value: arn:aws:iam::1234567890:mfa/User123\naws_mfa: false\naws_mfa_duration_seconds: 3600 # 1 hour\n\n# Command defaults\nterminal_default_service: app\nterminal_default_command: /bin/bash\nvscode_default_service: app\nvscode_default_dir: /app\n\n# If you are using a different flavor of VSCode, for example Cursor\n# set the appropriate binary for the code command\nvscode_binary: code\n\n# Scripts to run before and after\npre_start_hooks:\n  - .docker-env/pre-start.d/10-add-ssl-certificate-linux.sh\n  - .docker-env/pre-start.d/10-add-ssl-certificate-macos.sh\n  - .docker-env/pre-start.d/20-ports.sh\n  - .docker-env/pre-start.d/30-ssh-agent.sh\n\npost_start_hooks:\n  - .docker-env/post-start.d/10-show-message.sh\n\npost_stop_hooks:\n  - .docker-env/post-stop.d/10-node-modules.sh\n\n```\n\n## Hooks\n\nSupported hooks are:\n\n- pre-start\n- post-start\n- post-stop\n\nArguments passed to the hooks are `PROJECT_NAME` and `SERVICE_NAME` as positional arguments.\n\n```\n# In bash script use:\nPROJECT_NAME=\"$1\"\nSERVICE_NAME=\"$2\"\n```\n\nSample hooks can be found in `.docker-env/` directory to:\n\n- Generate SSL certificates\n- Run ssh-agent\n- Check ports availability\n\n## Troubleshooting\n\n### Error running docker command: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?\n\nSet `DOCKER_HOST` to docker socket in your home directory:\n\n```\nexport DOCKER_HOST=\"unix:///$HOME/.docker/run/docker.sock\"\n```\n\nor in Docker Desktop in Settings -\u003e Advanced select `Allow the default Docker socket to be used (requires password)`\n\n### Error getting AWS registry password: Unable to locate credentials. You can configure credentials by running \"aws configure\".\n\nExport `AWS_PROFILE` variables matching the profile in `~/.aws/credentials`:\n\n```\nexport AWS_PROFILE=default\n```\n\n## Release\n\n1. Change version in `version/version.go`\n2. Create a tag\n3. Run goreleaser\n\n```\nvim version/version.go\ngit commit -m 'First release'\ngit push origin master\ngit tag -a v1.0.0 -m \"First release\"\ngoreleaser release --clean\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcinhlybin%2Fdocker-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcinhlybin%2Fdocker-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcinhlybin%2Fdocker-env/lists"}