{"id":41421072,"url":"https://github.com/dokku/docker-orchestrate","last_synced_at":"2026-01-23T14:03:09.338Z","repository":{"id":329233355,"uuid":"1118688732","full_name":"dokku/docker-orchestrate","owner":"dokku","description":"A docker plugin for orchestrating compose deploys","archived":false,"fork":false,"pushed_at":"2025-12-28T10:12:37.000Z","size":232,"stargazers_count":4,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-30T15:18:12.454Z","etag":null,"topics":["docker","docker-compose"],"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/dokku.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"dokku","open_collective":"dokku","patreon":"dokku"}},"created_at":"2025-12-18T06:13:42.000Z","updated_at":"2025-12-28T10:12:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dokku/docker-orchestrate","commit_stats":null,"previous_names":["dokku/docker-orchestrate"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dokku/docker-orchestrate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdocker-orchestrate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdocker-orchestrate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdocker-orchestrate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdocker-orchestrate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dokku","download_url":"https://codeload.github.com/dokku/docker-orchestrate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dokku%2Fdocker-orchestrate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28693458,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T11:01:27.039Z","status":"ssl_error","status_checked_at":"2026-01-23T11:00:26.909Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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"],"created_at":"2026-01-23T14:03:08.079Z","updated_at":"2026-01-23T14:03:09.293Z","avatar_url":"https://github.com/dokku.png","language":"Go","funding_links":["https://github.com/sponsors/dokku","https://opencollective.com/dokku","https://patreon.com/dokku"],"categories":[],"sub_categories":[],"readme":"# docker-orchestrate\n\nA Docker CLI plugin to deploy Docker Compose services with support for rolling updates, custom healthchecks, and container naming conventions.\n\n## Why\n\nDocker Compose is often used as a way to deploy workloads on single servers, but does not natively support rolling restarts, despite [support in the specification](https://docs.docker.com/reference/compose-file/deploy/). This tool aims to fill that gap by implementing the `deploy.update_config` against a locally run `docker compose` project.\n\n## Installation\n\nTo install as a Docker CLI plugin, build the binary and move it to your Docker plugins directory:\n\n```bash\nmake install\n```\n\nOnce installed, this plugin is available via `docker orchestrate`.\n\n## Usage\n\nDeploy all services in a compose file:\n\n```bash\ndocker orchestrate deploy\n```\n\nDeploy a specific service:\n\n```bash\ndocker orchestrate deploy web\n```\n\nDeploy a service with a specific number of replicas:\n\n```bash\ndocker orchestrate deploy web --replicas 5\n```\n\nDeploy with one or more profiles enabled:\n\n```bash\ndocker orchestrate deploy --profile production\ndocker orchestrate deploy --profile production --profile monitoring\ndocker orchestrate deploy --profile production,monitoring\n```\n\nDeploy while skipping database services:\n\n```bash\ndocker orchestrate deploy --skip-databases\ndocker orchestrate deploy web --skip-databases\n```\n\n### Arguments\n\n- `service-name`: The name of a service in the compose file to deploy\n\n### Flags\n\n- `-f, --file`: Path to the Compose configuration file (defaults to `docker-compose.yaml` or `docker-compose.yml`).\n- `-p, --project-name`: Specify an alternate project name (defaults to the directory name).\n- `--project-directory`: Specify an alternate working directory.\n- `--container-name-template`: Go template for container names. Available variables: `.ProjectName`, `.ServiceName`, `.InstanceID`. Default: `{{.ProjectName}}-{{.ServiceName}}-{{.InstanceID}}`.\n- `--profile`: One or more profiles to enable. Can be specified multiple times or as a comma-separated list.\n- `--replicas`: Override the number of replicas for a specific service. This flag requires a `service-name` argument.\n- `--skip-databases`: Skip deploying database services - as detected by image - when deploying the entire project or a specific service.\n\n## Deployment Order\n\nWhen deploying a project, services are deployed in the following order:\n\n- If a `web` service exists with no dependencies, it is deployed first\n- All other services are deployed in dependency order (dependencies before dependents)\n- If the `web` service has dependencies, it follows normal dependency ordering\n\n### Detected Database Services\n\nWhen using the `--skip-databases` flag, `docker-orchestrate` automatically detects database services by examining the service's image repository. A service is considered a database if its image matches any of the following repositories:\n\n- `clickhouse/clickhouse-server`\n- `couchdb` (library/couchdb)\n- `elasticsearch` (library/elasticsearch)\n- `dokku/docker-grafana-graphite`\n- `mariadb`\n- `getmeili/meilisearch`\n- `memcached` (library/memcached)\n- `mongo` (library/mongo)\n- `mysql` (library/mysql)\n- `nats` (library/nats)\n- `omnisci/core-os-cpu`\n- `postgres` (library/postgres)\n- `fanout/pushpin`\n- `rabbitmq` (library/rabbitmq)\n- `redis` (library/redis)\n- `rethinkdb` (library/rethinkdb)\n- `solr` (library/solr)\n- `typesense/typesense`\n\nDetection is based on the image repository name (short name), so it works regardless of the image tag or registry. For example, both `postgres:14` and `myregistry.com/library/postgres:latest` would be detected as database services.\n\n### Skipping Services by Label\n\nYou can skip individual services by adding the `com.dokku.orchestrate/skip` label with a value of `\"true\"` to the service definition. This is useful when you want to exclude specific services from deployment without using the `--skip-databases` flag.\n\n```yaml\nservices:\n  web:\n    image: nginx:alpine\n    labels:\n      com.dokku.orchestrate/skip: \"true\"\n  api:\n    image: myapp/api:latest\n    # This service will be deployed normally\n```\n\nWhen a service has this label set to `\"true\"`, it will be skipped during deployment.\n\n**Note**: The label value must be exactly the string `\"true\"` (case-sensitive). Other values like `\"false\"`, `\"yes\"`, or `\"1\"` will not trigger skipping.\n\n### Skipping Model Services\n\nServices that define models (via the `models` field) are automatically skipped during deployment. Model services are typically used for service composition and should not be deployed directly by `docker-orchestrate`.\n\n```yaml\nservices:\n  app:\n    models:\n      model1:\n        # model configuration\n  web:\n    image: nginx:alpine\n    # This service will be deployed normally\n```\n\n### Skipping Provider Services\n\nServices that use external providers (defined via the `provider` field) are automatically skipped during deployment. Provider services are typically managed by external systems (like cloud providers) and should not be deployed by `docker-orchestrate`.\n\n```yaml\nservices:\n  database:\n    provider:\n      type: awesomecloud\n      options:\n        type: mysql\n        foo: bar\n  web:\n    image: nginx:alpine\n    # This service will be deployed normally\n```\n\n## Script Extensions\n\nIn addition to native healthchecks, `docker-orchestrate` supports extended functionality via custom fields within the `update_config` section of a service.\n\n### Script Healthchecks\n\nThe tool supports an extended healthcheck mechanism via the `x-healthcheck-host-command` field.\n\n```yaml\nservices:\n  web:\n    deploy:\n      replicas: 3\n      update_config:\n        parallelism: 1\n        order: start-first\n        x-healthcheck-host-command: |\n          curl -f http://{{.ContainerIP}}:8080/health\n```\n\nThe script healthcheck runs after the standard Docker healthcheck (if defined) succeeds.\n\n### Stop Commands\n\nThe tool supports several types of stop commands that are executed before and after a container is terminated (e.g., during a rolling update or scale down):\n\n- **`x-pre-stop-host-command`**: Executed on the host before stopping a container\n- **`x-pre-stop-command`**: Executed inside the container before stopping (synchronously via Docker SDK)\n- **`x-post-stop-host-command`**: Executed on the host after stopping a container\n\n```yaml\nservices:\n  web:\n    deploy:\n      update_config:\n        x-pre-stop-host-command: |\n          curl -f http://{{.ContainerIP}}:8080/shutdown\n        x-pre-stop-command: |\n          #!/bin/sh\n          echo \"Stopping service gracefully...\"\n          kill -TERM 1\n        x-post-stop-host-command: |\n          echo \"Container {{.ContainerShortID}} has been stopped\"\n```\n\n#### Container Pre-Stop Commands\n\nThe `x-pre-stop-command` field allows you to run scripts **inside the container** before it is stopped. This is useful for graceful shutdowns, cleanup tasks, or any operations that need to run within the container's environment.\n\n```yaml\nservices:\n  app:\n    deploy:\n      update_config:\n        x-pre-stop-command: |\n          #!/bin/bash\n          # Graceful shutdown\n          pkill -TERM -P 1\n          sleep 2\n          # Cleanup\n          rm -f /tmp/app.lock\n```\n\n- Scripts are written to `/tmp/pre-stop.sh` inside the container\n- Scripts run synchronously - `docker-orchestrate` waits for completion before stopping the container\n- Interpreter selection:\n  - If the script has a shebang (e.g., `#!/usr/bin/env bash`), that interpreter is used\n  - Otherwise, the container's `Config.Shell` property is used\n  - Falls back to `/bin/sh` if neither is available\n- Shebang parsing:\n  - `#!/usr/bin/env bash` → `/bin/bash -c`\n  - `#!/bin/sh` → `/bin/sh -c`\n  - `#!/usr/bin/python3` → `/usr/bin/python3 -c`\n  - Other interpreters are supported based on the shebang\n\n**Note**: The container must have the following binaries available:\n\n- `/bin/sh` (or the shell specified in `Config.Shell`) - required for script execution\n- The interpreter specified in the shebang (if present) - must be available in the container's PATH\n\n#### Detached Execution\n\nBy default, stop commands run synchronously and `docker-orchestrate` waits for them to complete before proceeding. You can configure commands to run in detached mode using `x-pre-stop-host-command-detached` and `x-post-stop-host-command-detached`. When set to `true`, the command runs asynchronously and will continue executing even if `docker-orchestrate` exits.\n\n```yaml\nservices:\n  web:\n    deploy:\n      update_config:\n        x-pre-stop-host-command: |\n          # Long-running cleanup task\n          ./cleanup-script.sh {{.ContainerID}}\n        x-pre-stop-host-command-detached: true\n        x-post-stop-host-command: |\n          # Send notification asynchronously\n          curl -X POST http://monitoring.example.com/notify\n        x-post-stop-host-command-detached: true\n```\n\n- Detached commands run in the background and do not block deployment\n- Detached commands continue running even if `docker-orchestrate` exits or is interrupted\n- Only boolean values (`true` or `false`) are allowed\n- If not specified, the default is `false` (synchronous execution)\n- Invalid values (non-boolean types) will result in an error\n\n### Script Templating\n\nBoth `x-healthcheck-host-command`, `x-pre-stop-host-command`, and `x-post-stop-host-command` are treated as Go templates and have access to:\n\n- `.ContainerID`: Full ID of the container.\n- `.ContainerShortID`: First 12 characters of the container ID.\n- `.ContainerIP`: Internal IP address of the container.\n- `.ServiceName`: Name of the service.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokku%2Fdocker-orchestrate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdokku%2Fdocker-orchestrate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdokku%2Fdocker-orchestrate/lists"}