{"id":20221945,"url":"https://github.com/gmpassos/docker_commander","last_synced_at":"2026-02-18T03:08:53.014Z","repository":{"id":43035890,"uuid":"337627612","full_name":"gmpassos/docker_commander","owner":"gmpassos","description":"A Docker manager, for local and remote host machines. Works with personalized containers and pre-configured popular containers.","archived":false,"fork":false,"pushed_at":"2024-11-17T21:17:50.000Z","size":331,"stargazers_count":8,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-03T03:57:08.174Z","etag":null,"topics":["docker","manager","portable","remote"],"latest_commit_sha":null,"homepage":"","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gmpassos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["gmpassos"]}},"created_at":"2021-02-10T05:33:51.000Z","updated_at":"2025-03-26T23:28:41.000Z","dependencies_parsed_at":"2025-04-10T16:40:27.566Z","dependency_job_id":null,"html_url":"https://github.com/gmpassos/docker_commander","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/gmpassos/docker_commander","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmpassos%2Fdocker_commander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmpassos%2Fdocker_commander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmpassos%2Fdocker_commander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmpassos%2Fdocker_commander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gmpassos","download_url":"https://codeload.github.com/gmpassos/docker_commander/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gmpassos%2Fdocker_commander/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29566366,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T00:47:08.760Z","status":"online","status_checked_at":"2026-02-18T02:00:09.468Z","response_time":162,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","manager","portable","remote"],"created_at":"2024-11-14T06:54:55.775Z","updated_at":"2026-02-18T03:08:48.007Z","avatar_url":"https://github.com/gmpassos.png","language":"Dart","funding_links":["https://github.com/sponsors/gmpassos"],"categories":[],"sub_categories":[],"readme":"# docker_commander\n\n[![pub package](https://img.shields.io/pub/v/docker_commander.svg?logo=dart\u0026logoColor=00b9fc)](https://pub.dartlang.org/packages/docker_commander)\n[![Null Safety](https://img.shields.io/badge/null-safety-brightgreen)](https://dart.dev/null-safety)\n\n[![Docker image size](https://img.shields.io/docker/image-size/gmpassos/docker_commander?label=docker%20image%20size)](https://hub.docker.com/r/gmpassos/docker_commander)\n[![Docker puuls](https://img.shields.io/docker/pulls/gmpassos/docker_commander)](https://hub.docker.com/r/gmpassos/docker_commander)\n[![Docker build](https://img.shields.io/docker/cloud/build/gmpassos/docker_commander)](https://hub.docker.com/r/gmpassos/docker_commander/builds)\n\n[![Dart CI](https://github.com/gmpassos/docker_commander/actions/workflows/dart.yml/badge.svg?branch=master)](https://github.com/gmpassos/docker_commander/actions/workflows/dart.yml)\n\n[![GitHub Tag](https://img.shields.io/github/v/tag/gmpassos/docker_commander?logo=git\u0026logoColor=white)](https://github.com/gmpassos/docker_commander/releases)\n[![New Commits](https://img.shields.io/github/commits-since/gmpassos/docker_commander/latest?logo=git\u0026logoColor=white)](https://github.com/gmpassos/docker_commander/network)\n[![Last Commits](https://img.shields.io/github/last-commit/gmpassos/docker_commander?logo=git\u0026logoColor=white)](https://github.com/gmpassos/docker_commander/commits/master)\n[![Pull Requests](https://img.shields.io/github/issues-pr/gmpassos/docker_commander?logo=github\u0026logoColor=white)](https://github.com/gmpassos/docker_commander/pulls)\n[![Code size](https://img.shields.io/github/languages/code-size/gmpassos/docker_commander?logo=github\u0026logoColor=white)](https://github.com/gmpassos/docker_commander)\n\n[![License](https://img.shields.io/github/license/gmpassos/docker_commander?logo=open-source-initiative\u0026logoColor=green)](https://github.com/gmpassos/docker_commander/blob/master/LICENSE)\n\n`docker_commander` is a [Docker][docker] manager to easily automate a\nDocker Daemon, or a Docker Swarm, with:\n  - Local and remote management.\n  - Helpers to build a Docker network and automatically configure running containers.\n  - Helpers to manipulate files inside a running container.\n  - Formulas: pre-defined code to install/uninstall containers.\n  - Built-in pre-configured containers:\n    - [PostgreSQL][postgresql]\n    - [Apache HTTPD][apache]\n    - [NGINX][nginx]\n\n[docker]:https://www.docker.com/\n\n-------------------------------------------------------------------------------\n\n## Running `docker_commander` [image][docker_commander_server_image]\n\nA [Docker][docker] image of `docker_commander` is provided at [Docker HUB][docker_commander_server_image],\nallowing an easy and fast way to use `docker_commander` in any environment with Docker (even without Dart).\n\nPull the Docker image:\n\n```shell\ndocker pull gmpassos/docker_commander\n```\n\n### SERVER MODE (docker_commander_server):\n\nRun the `docker_commander` image in SERVER mode, mapping port `8099` and Docker Host Daemon socket file (`/var/run/docker.sock`).\n\n```shell\ndocker run --name docker_commander_server -d -t --rm -v /var/run/docker.sock:/var/run/docker.sock -p 8099:8099 gmpassos/docker_commander --server userx pass123\n```\n\nYou need to provide an username and password (the parameters `userx`and `pass123` above) to control the access to this `docker_commander` server.\nYou will pass this credential, and the public mapped port (8099) to the `DockerHostRemote`, allowing it to connect to the server container.\nIf you need to restrict address access, pass the parameter `--private`.\n\nFollow the server output:\n\n```shell\ndocker logs docker_commander_server -f\n```\n\n*NOTE:\nTo enable control of Docker Daemon from the `docker_commander` server container, you need\nto map the Docker Host Daemon socket file (`/var/run/docker.sock`). This won't require to run the\ncontainer in a `--privileged` context or as root.*\n\n### CONSOLE MODE (docker_commander_console):\n\nRun the `docker_commander` image in CONSOLE mode, passing `--console`:\n\n```shell\ndocker run -it --rm gmpassos/docker_commander --console userx your.server.host 8099\n```\n\nConsole example:\n\n```text\n\u003cCONSOLE MODE\u003e\nARGS: [--console, userx, your.server.host, 8099]\n\n[docker_commander server: your.server.host:8099]\nPlease, provide the password for user 'userx':\npassword\u003e pass123\n------------------------------------------------------------------------------\nDockerCommanderConsole{dockerCommander: DockerCommander{dockerHost: DockerHostRemote{serverHost: your.server.host, serverPort: 8099, secure: false, username: userx}, initialized: false. lastDaemonCheck: null}}\nInitializing...\nInitialization: true\n------------------------------------------------------------------------------\n\n$\u003e ps\n------------------------------------------------------------------------------\n\u003e\u003e CONTAINER ID   IMAGE                       COMMAND                  CREATED             STATUS             PORTS                    NAMES\n\u003e\u003e 0f229773e36f   gmpassos/docker_commander   \"/usr/bin/dart run b…\"   About an hour ago   Up About an hour   0.0.0.0:8099-\u003e8099/tcp   docker_commander_server\n------------------------------------------------------------------------------\nEXIT_CODE: 0\n\n$\u003e help\n...\n```\n\n### For more information:\n\n- See the [Docker HUB Repository of `docker_commander`][docker_commander_server_image]\n\n[docker_commander_server_image]:https://hub.docker.com/r/gmpassos/docker_commander\n\n-------------------------------------------------------------------------------\n\n## Formulas\n\nFormulas are a very easy way to install/uninstall and handle containers and services\nin `docker_commander`.\n\nYou can use `docker_commander` formulas from a repository. Below there's a simple\nexample of how to use the standard repository (`DockerCommanderFormulaRepositoryStandard`)\nfrom a Dart code.\n\n```dart\nimport 'package:docker_commander/docker_commander_vm.dart';\n\nvoid main() async {\n  // Creates a `DockerCommander` for a local host machine:\n  var dockerCommander = DockerCommander(DockerHostLocal());\n  \n  // Initialize `DockerCommander`:\n  await dockerCommander.initialize();\n  \n  // The formula repository to use:\n  var repository = DockerCommanderFormulaRepositoryStandard();\n\n  // Get the `apache` formula source:\n  var formulaSource = await repository.getFormulaSource('apache');\n\n  // Get the formula instance and perform setup:\n  var formula = formulaSource!.toFormula() ;\n  \n  formula.setup(dockerCommander: dockerCommander);\n\n  // Install the formula:\n  var installed = await formula.install();\n\n  //...\n\n  // Stop the formula:\n  var stopped = await formula.stop();\n\n  //...\n  \n  // Start the formula:\n  var start = await formula.start();\n\n  //...\n  \n  // Uninstall the formula:\n  var uninstalled = await formula.uninstall();\n  \n}\n\n```\n\n### Defining a Formula\n\nFormulas are pre-defined codes to handle install, uninstall, start, stop and other extra operations\nthat a container, or group of containers, can have.\n\nFormulas are defined using a high level languages, like `Dart` or `Java`. Any language supported\nby [ApolloVM][ApolloVM] can be used.\n\nHere's a simple example of an `Apache` formula source code in `Dart`:\n\n```dart\n\nclass ApacheFormula {\n\n  String getVersion() {\n    return '1.0';\n  }\n\n  void install() {\n    cmd('create-container apache httpd latest --port 80 --hostname apache');\n    start();\n  }\n\n  void start() {\n    cmd('start apache');\n  }\n\n  void stop() {\n    cmd('stop apache');\n  }\n\n  void uninstall() {\n    stop();\n    cmd('remove-container apache --force');\n  }\n\n}\n\n```\n\nA formula source code will be parsed and executed by [ApolloVM][ApolloVM],\nallowing dynamic loading and execution, in a sandbox, of any formula by `docker_commander`.\n\n-------------------------------------------------------------------------------\n\n## Using a Formula through `docker_commander_console`:\n\nTo list the available formulas in the server:\n\n```shell\n$\u003e list-formulas\n\n------------------------------------------------------------------------------\nFORMULAS:\n\n  apache gitlab\n\n------------------------------------------------------------------------------\n```\n\nTo show information of a formula:\n\n```shell\n$\u003e show-formula gitlab\n------------------------------------------------------------------------------\nFORMULA: gitlab\n\nCLASS NAME: GitLabFormula\n\nFIELDS:\n\n  - imageGitlab: gitlab/gitlab-ce\n  - imageGitlabRunner: gitlab/gitlab-runner\n  - imageRunner: google/dart\n  - network: gitlab-net\n  - hostGitlabConfigPath: /srv/gitlab-runner/config\n\nFUNCTIONS:\n\n  - getVersion\n  - pull\n  - pullRunner\n  - install\n  - installRunner\n  - registerRunner\n  - start\n  - stop\n  - startRunner\n  - stopRunner\n  - uninstall\n  - uninstallRunner\n\n------------------------------------------------------------------------------\n```\n\nUsing a formula.\n\n```shell\n## Pull images:\n$\u003e formula-exec gitlab pull\n$\u003e formula-exec gitlab pullRunner\n\n## Install images (create containers and start):\n$\u003e formula-exec gitlab install\n\n## Install optional GitLab Runner,\n## personalizing field \"hostGitlabConfigPath\":\n$\u003e formula-exec gitlab installRunner --hostGitlabConfigPath /host/path/to/gitlab-config-dir/\n\n## Register GitLab Runner,\n## passing the host and token of GitLab,\n## and the personalized field \"hostGitlabConfigPath\":\n$\u003e formula-exec gitlab registerRunner 172.30.0.2 zysByxVr9tss18BvLFxj --hostGitlabConfigPath /host/path/to/gitlab-config-dir/\n\n## Starts the GitLab Runner, once it's registered.\n$\u003e formula-exec gitlab startRunner\n```\n\n*NOTE: The function `installRunner` and `registerRunner`\nare personalizing the path of the GitLab config directory in\nthe host machine using the field `hostGitlabConfigPath`.*\n\nStopping and uninstalling a formula:\n\n```shell\n$\u003e formula-exec gitlab stop\n\n$\u003e formula-exec gitlab uninstall\n```\n\n-------------------------------------------------------------------------------\n\n## ApolloVM\n\n[ApolloVM][ApolloVM] is a simple and portable VM for `Dart` and `Java`,\nthat can at runtime dynamically parse, execute and generate code in any\nplatform (native, JS/Browser and Flutter).\n\n[ApolloVM]: https://pub.dev/packages/apollovm\n\n-------------------------------------------------------------------------------\n\n## Dart Usage\n\n### Local Docker\n\nHere's a simple usage example in `Dart` for a local host machine:\n\n```dart\nimport 'package:docker_commander/docker_commander_vm.dart';\n\nvoid main() async {\n  // Creates a `DockerCommander` for a local host machine:\n  var dockerCommander = DockerCommander(DockerHostLocal());\n  \n  // Initialize `DockerCommander`:\n  await dockerCommander.initialize();\n  // Ensure that Docker daemon is running.\n  await dockerCommander.checkDaemon();\n\n  // Run Docker image `hello-world`:\n  var dockerContainer = await dockerCommander.run('hello-world');\n\n  // Waits the container to exit, and gets the exit code:\n  var exitCode = await dockerContainer.waitExit();\n  \n  // Gets all the STDOUT as [String]. \n  var output = dockerContainer.stdout.asString;\n  \n  print(output);\n  print('EXIT CODE: $exitCode');\n}\n\n```\n\n\n### Remote Docker\n\nHere's another usage example for a remote host machine:\n\n#### Server\n\nStart `DockerHostServer`:\n\n```dart\nimport 'package:docker_commander/docker_commander_vm.dart';\n\nvoid main() async {\n  \n  // A simple username and password table:\n  var authenticationTable = AuthenticationTable({'admin': '123'});\n\n  // A `DockerHost` Server at port 8099:\n  var hostServer = DockerHostServer(\n          (user, pass) async =\u003e authenticationTable.checkPassword(user, pass),\n      8099);\n\n  // Starts the server and wait initialization:\n  await hostServer.startAndWait();\n  \n}\n\n```\n\n#### Client\n\nClient side using `DockerHostRemote`. Note that the code below\ncan run in any platform, like JS (in a Web Browser) or any Flutter platform (Android, iOS, Web, Linux, macOS, Windows):\n\n```dart\nimport 'package:docker_commander/docker_commander.dart';\n\nvoid main() async {\n\n  // Connect to a `DockerHost` running at '10.0.0.52:8099'\n  var dockerHostRemote = DockerHostRemote('10.0.0.52', 8099, username: 'admin', password: '123');\n\n  // Creates a `DockerCommander` for a remote host machine:\n  var dockerCommander = DockerCommander(dockerHostRemote);\n  \n  // Initialize `DockerCommander` (at remote server):\n  await dockerCommander.initialize();\n  // Ensure that Docker daemon is running (at remote server):\n  await dockerCommander.checkDaemon();\n\n  // Run Docker image `hello-world` (at remote server):\n  var dockerContainer = await dockerCommander.run('hello-world');\n\n  // The behavior is the same of the example using `DockerHostLocal`.\n  // The internal `DockerRunner` will sync remote output (stdout/sdterr) automatically!\n\n  // ...\n  \n  // Gets all the STDOUT as [String]. \n  var output = dockerContainer.stdout.asString;\n  print(output);\n  \n  // ...\n  \n}\n\n```\n\n-------------------------------------------------------------------------------\n\n## PostgreSQLContainer\n\nA pre-configured [PostgreSQL][postgresql] Container:\n\n```dart\nimport 'package:docker_commander/docker_commander_vm.dart';\n\nvoid main() async {\n\n  // Creates a `DockerCommander` for a local host machine:\n  var dockerCommander = DockerCommander(DockerHostLocal());\n  // Initialize `DockerCommander`:\n  await dockerCommander.initialize();\n  \n  // Start PostgreSQL container:\n  var dockerContainer = await PostgreSQLContainer().run(dockerCommander);\n\n  // Print the current STDOUT of the container:\n  var output = dockerContainer.stdout.asString;\n  print(output);\n\n  // Execute inside the container a `psql` command:\n  var execPsql = await dockerContainer.exec('/usr/bin/psql',\n      ['-d','postgres', '-U','postgres', '-c','\\\\l']);\n\n  // Wait command to execute:\n  var execPsqlExitCode = await execPsql.waitExit();\n\n  // Command output:\n  print( execPsql.stdout.asString );\n  \n  // Stops PostgreSQL, with a timeout of 20s:\n  await dockerContainer.stop(timeout: Duration(seconds: 20));\n\n  // Wait PostgreSQL to exit and get exit code:\n  var exitCode = await dockerContainer.waitExit();\n\n  // ...\n\n}\n\n```\n\n[postgresql]:https://www.postgresql.org/\n\n-------------------------------------------------------------------------------\n\n## ApacheHttpdContainer\n\nA pre-configured container for the famous [Apache HTTPD][apache]:\n\n```dart\nimport 'package:docker_commander/docker_commander_vm.dart';\nimport 'package:mercury_client/mercury_client.dart';\n\nvoid main() async {\n    var dockerCommander = DockerCommander(DockerHostLocal());\n    // Initialize `DockerCommander`:\n    await dockerCommander.initialize();\n    \n    // The host port to map internal container port (httpd at port 80).\n    var apachePort = 8081;\n    \n    var dockerContainer = await ApacheHttpdContainer()\n        .run(dockerCommander, hostPorts: [apachePort]);\n    \n    // Get HTTPD configuration file:\n    var httpdConf = await dockerContainer.execCat('/usr/local/apache2/conf/httpd.conf');\n\n    // Get the host port of Apache HTTPD.\n    var hostPort = dockerContainer.hostPorts[0];\n    // Request a HTTP GET using hostPort:\n    var response = await HttpClient('http://localhost:$hostPort/').get('index.html');\n    \n    // The body of the response\n    var content = response.bodyAsString;\n    print(content);\n    \n    // Stop Apache HTTPD:\n    await dockerContainer.stop(timeout: Duration(seconds: 5));\n\n}\n\n```\n\n[apache]:https://httpd.apache.org/\n\n-------------------------------------------------------------------------------\n\n## NginxContainer\n\nA pre-configured container for the famous [NGINX][nginx] proxy server.\n\nThis example shows a [NGINX][nginx] reverse proxy, that redirects HTTP requests at `localhost:4082`\nto the internal Apache container, with hostname `apache`, at port `80`.\n\n```dart\nimport 'package:docker_commander/docker_commander_vm.dart';\nimport 'package:mercury_client/mercury_client.dart';\n\nvoid main() async {\n  var dockerCommander = DockerCommander(DockerHostLocal());\n  // Initialize `DockerCommander`:\n  await dockerCommander.initialize();\n\n  // Docker Network for Apache HTTPD and NGINX containers:\n  var network = await dockerCommander.createNetwork();\n\n  // Start Apache HTTPD, mapping port 80 to 4081.\n  var apacheContainer = await ApacheHttpdContainer().run(dockerCommander,\n      hostPorts: [4081], network: network, hostname: 'apache');\n\n  // Generate a NGINX configuration, mapping domain `localhost` to\n  // docker host `apache` at port 80 (without HTTPS).\n  var nginxConfig = NginxReverseProxyConfigurer(\n      [NginxServerConfig('localhost', 'apache', 80, false)]).build();\n\n  // Start a NGINX container using generated configuration.\n  var nginxContainer = await NginxContainer(nginxConfig, hostPorts: [4082])\n      .run(dockerCommander, network: network, hostname: 'nginx');\n\n  // Request apache:80 (mapped in the host machine to localhost:4081)\n  // trough NGINX reverse proxy at localhost:4082\n  var response = await HttpClient('http://localhost:4082/').get('');\n\n  // The Apache HTTPD response content:\n  var apacheContent = response.bodyAsString;\n\n  print(apacheContent);\n\n  // Stop NGINX:\n  await nginxContainer.stop(timeout: Duration(seconds: 5));\n\n  // Apache Apache HTTPD:\n  await apacheContainer.stop(timeout: Duration(seconds: 5));\n\n  // Remove Docker network:\n  await dockerCommander.removeNetwork(network);\n}\n```\n\n[nginx]:https://www.nginx.com/\n\n-------------------------------------------------------------------------------\n\n## See Also\n\nSee [package docker_commander_test][docker_commander_test], for unit test framework with [Docker][docker] containers.\n\nThanks to [isoos@GitHub][github_isoos], author of the precursor package `docker_process`, that was substituted by this one. \n\n[docker_commander_test]:https://github.com/gmpassos/docker_commander_test\n[docker]:https://www.docker.com/\n[github_isoos]: https://github.com/isoos\n\n## Features and bugs\n\nPlease file feature requests and bugs at the [issue tracker][tracker].\n\n[tracker]: https://github.com/gmpassos/docker_commander/issues\n\n## Author\n\nGraciliano M. Passos: [gmpassos@GitHub][github_gmp].\n\n[github_gmp]: https://github.com/gmpassos\n\n## License\n\n[Apache License - Version 2.0][apache_license]\n\n[apache_license]: https://www.apache.org/licenses/LICENSE-2.0.txt\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmpassos%2Fdocker_commander","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgmpassos%2Fdocker_commander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgmpassos%2Fdocker_commander/lists"}