{"id":20141333,"url":"https://github.com/justincarter/docker-workbench","last_synced_at":"2025-04-09T18:40:55.815Z","repository":{"id":57528223,"uuid":"58539849","full_name":"justincarter/docker-workbench","owner":"justincarter","description":"Provision a Docker Workbench for use with docker-machine and docker-compose","archived":false,"fork":false,"pushed_at":"2022-11-21T01:04:14.000Z","size":179,"stargazers_count":16,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-23T20:43:17.906Z","etag":null,"topics":["docker","docker-compose","docker-machine","docker-workbench","go"],"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/justincarter.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}},"created_at":"2016-05-11T11:40:00.000Z","updated_at":"2022-11-28T11:40:07.000Z","dependencies_parsed_at":"2023-01-22T01:58:30.938Z","dependency_job_id":null,"html_url":"https://github.com/justincarter/docker-workbench","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justincarter%2Fdocker-workbench","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justincarter%2Fdocker-workbench/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justincarter%2Fdocker-workbench/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/justincarter%2Fdocker-workbench/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/justincarter","download_url":"https://codeload.github.com/justincarter/docker-workbench/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248089755,"owners_count":21045962,"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","docker-machine","docker-workbench","go"],"created_at":"2024-11-13T21:57:03.648Z","updated_at":"2025-04-09T18:40:55.790Z","avatar_url":"https://github.com/justincarter.png","language":"Go","readme":"# Docker Workbench\n\n[![Build Status](https://travis-ci.org/justincarter/docker-workbench.svg?branch=master)](https://travis-ci.org/justincarter/docker-workbench)\n[![codebeat badge](https://codebeat.co/badges/271f8ad5-385f-4edb-89da-12d8ce8fa654)](https://codebeat.co/projects/github-com-justincarter-docker-workbench)\n[![Go Report Card](https://goreportcard.com/badge/github.com/justincarter/docker-workbench)](https://goreportcard.com/report/github.com/justincarter/docker-workbench)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/justincarter/docker-workbench/master/LICENSE)\n[![GitHub release](https://img.shields.io/github/release/justincarter/docker-workbench.svg?maxAge=86400)](https://github.com/justincarter/docker-workbench/releases/latest)\n\n`docker-workbench` is a utility for simplifying the creation of Docker-based development environments in VirtualBox with `docker-machine`.\n\nThe primary goals of `docker-workbench` are;\n\n1. To make it easy to create Docker machines in VirtualBox with sensible defaults (CPUs, disk size, RAM, etc)\n2. To make it easy to run multiple containerised web applications without managing DNS, hosts files or ports\n3. To provide a standard `/workbench` shared folder to allow `docker-compose` volumes work the same for multiple users, cross-platform\n4. To allow mobile, tablet and other network devices to easily access the containerised applications\n\n\n## Installation\n\n### 1. Install Go\n\n`docker-workbench` is written in Go. To install and set up Go;\n\n1. Download and install Go (https://golang.org/)\n2. Create a \"workspace\" folder to store your Go source and binaries (e.g. `c:\\workspace` or `~/workspace`)\n3. Set the `GOPATH` environment variable to the path of the \"workspace\" folder you created\n4. Append to your `PATH` environment variable `%GOPATH%\\bin` (for Windows) or `$GOPATH/bin` (for Linux/Mac)\n\n### 2. Install Docker Workbench\n\nTo install `docker-workbench` using Go;\n\n    go install github.com/justincarter/docker-workbench@latest\n\n### 3. Install Additional Requirements\n\nTo use `docker-workbench` you will also need to install the following;\n\n#### For Windows\n\n1. Oracle VirtualBox 5.x (https://www.virtualbox.org/)\n2. Git Bash (https://git-for-windows.github.io/)\n3. Docker CLI Tools (docker, docker-machine, docker-compose) \n\nYou can install the Docker CLI Tools by first installing Chocolatey;  \nhttps://chocolatey.org/\n\nThen from an Administrative Command Prompt;\n\n    C:\\\u003e chocolatey install docker\n    C:\\\u003e chocolatey install docker-machine\n    C:\\\u003e chocolatey install docker-compose\n\nAlternatively you can install the legacy Docker Toolbox for Windows (https://docs.docker.com/toolbox/toolbox_install_windows/). Note: Do not enable Hyper-V when prompted, otherwise Virtualbox will not work.\n\n#### For Mac\n\n1. Oracle VirtualBox 5.x (https://www.virtualbox.org/)\n2. Docker CLI Tools (docker, docker-machine, docker-compose) \n\nYou can install the Docker CLI Tools by first installing Homebrew;  \nhttps://brew.sh/\n\n    $ brew install docker\n    $ brew install docker-machine\n    $ brew install docker-compose\n\nAlternatively you can install the legacy Docker Toolbox for Mac (https://docs.docker.com/toolbox/toolbox_install_mac/).\n\n#### For Linux\n\n1. Docker Engine (https://docs.docker.com/install/)\n2. Docker Machine (https://docs.docker.com/machine/install-machine/)\n3. Docker Compose (https://docs.docker.com/compose/install/)\n4. Oracle VirtualBox 5.x (https://www.virtualbox.org/)\n\n\n## Usage\n\n    docker-workbench v1.5\n    Provision a Docker Workbench for use with docker-machine and docker-compose\n\n    Usage:\n    docker-workbench [options] COMMAND\n\n    Options:\n    --help, -h    show help\n    --version, -v print the version\n\n    Commands:\n    create        Create a new workbench machine in the current directory\n    up            Start the workbench machine and show details\n    proxy         Start a reverse proxy to the app in the current directory\n    help          Shows a list of commands or help for one command\n\n    Run 'docker-workbench help COMMAND' for more information on a command.\n\n\n## Creating a Docker Workbench\n\nA Docker Workbench is created in the context of the working directory from which the `docker-workbench create` command is run. The working directory is automatically configured as a shared folder inside the VM that is always named `/workbench`.\n\nThe following example will create a Docker Workbench called `workbench` (named automatically from `d:\\workbench`);\n\n    $ mkdir /d/workbench\n    $ cd /d/workbench\n    $ docker-workbench create\n\nWhen `docker-workbench create` is run, it does a few simple things;\n\n- The default CPU cores for the VM is set to 2\n- The default RAM for the VM is set to 2GB\n- The default disk size for the VM is set to 60GB\n- The `docker-machine` command is run to create the VM\n- The Docker Workbench reverse proxy container is installed and set to always run\n- The `/workbench` shared folder is set to the working directory\n\nYou may use any standard Docker Machine environment variables used by the Oracle VirtualBox driver to customise the machine creation (e.g. default to use more cores, more RAM, etc) (https://docs.docker.com/machine/drivers/virtualbox/)\n\n\n## Running an application\n\nThe Docker Workbench directory can contain multiple applications, each in their own sub-directory (typically cloned from a Git respoistory).\n\nHere is an example of a trivial web application called \"myapp\" using Lucee 4.5 and Nginx, which has been placed inside the `workbench` directory;\n\n    myapp\n    ├── docker-compose.yml\n    └── www\n        └── index.cfm\n\nThe reverse proxy included with Docker Workbench will automatically route traffic to any containers that listen on port 80 and are configured with a `VIRTUAL_HOST` environment variable that specifies the host headers (wild cards allowed) that the application should respond to.\n\nWith Docker Workbench it is a requirement to use highly consistent naming for folders and host headers because this makes configuration obvious.\n\nThe `docker-compose.yml` file for \"myapp\" looks like this:\n\n    myapp:\n      image: lucee/lucee:nginx\n      environment:\n        - \"VIRTUAL_HOST=myapp.*\"\n      volumes:\n        - \"/workbench/myapp/www:/var/www\"\n\nNote the consistent naming; \"myapp\" is the directory name of the application, which matches the service name at the top of the .yml file, the environment variable `VIRTUAL_HOST` wildcard prefix, and also the parth used in the volume which maps the \"www\" folder into the container.\n\nBefore running the application, we can ensure that the Docker Workbench is running and get some useful info about it by running the `docker-workbench up` command from with the \"myapp\" directory.\n\n    $ cd myapp\n    $ docker-workbench up\n    Starting \"workbench\"...\n    Machine \"workbench\" is already running.\n\n    Run the following command to set this machine as your default:\n    eval \"$(docker-machine env workbench)\"\n\n    Start the application:\n    docker-compose up\n\n    Browse the workbench using:\n    http://myapp.192.168.99.100.nip.io/\n\nThe next step is to set the machine as the default, which will set environment variables that allow us to work with docker, docker-machine and docker-compose. The output above tells us the command to run;\n\n    $ eval \"$(docker-machine env workbench)\"\n\nThe output above also tells us the URL that the application will be available on when it is running. \n\n    http://myapp.192.168.99.100.nip.io/\n\nThis URL is made up of the value supplied in the VIRTUAL_HOST which must match the directory of the application (\"myapp\"), the IP address of the Docker Workbench VM (assigned by VirtualBox using DHCP from the Docker Machine network adapter), and \".nip.io\" which is a wildcard DNS service that resolves names to their matching IP addresses. This means we do not have to manage our own DNS or hosts files or bother with unique, difficult to remember port numbers for each application.\n\nThe final step is to start the application using Docker Compose, as mentioned in the output above;\n\n    $ docker-compose up\n\nWhen the application finishes starting up you will be able to browse to the app using the URL above, and output similar to below will appear in the console;\n\n    myapp_1 | lucee-server-root:/opt/lucee/server/lucee-server\n    myapp_1 | ===================================================================\n    myapp_1 | SERVER CONTEXT\n    myapp_1 | -------------------------------------------------------------------\n    myapp_1 | - config:/opt/lucee/server/lucee-server/context\n    myapp_1 | - loader-version:6.1\n    myapp_1 | ===================================================================\n    myapp_1 |\n    myapp_1 | 2010-01-25 08:47:17,423 INFO success: nginx entered RUNNING state, process has stayed up for \u003e than 1 seconds (startsecs) \n    myapp_1 | 2010-01-25 08:47:17,423 INFO success: lucee entered RUNNING state, process has stayed up for \u003e than 1 seconds (startsecs) \n    myapp_1 | Fri Jan 25 08:47:17 UTC 2019-464 using JRE Date Library\n    myapp_1 | Fri Jan 25 08:47:17 UTC 2019-756 Start CFML Controller\n    myapp_1 | Fri Jan 25 08:47:17 UTC 2019 Loaded Lucee Version 5.3.1.92\n    myapp_1 | ===================================================================\n    myapp_1 | WEB CONTEXT (cbe856ff790c9ba5208811309bdf168b)\n    myapp_1 | -------------------------------------------------------------------\n    myapp_1 | - config:/opt/lucee/web (custom setting)\n    myapp_1 | - webroot:/var/www/\n    myapp_1 | - hash:cbe856ff790c9ba5208811309bdf168b\n    myapp_1 | - label:cbe856ff790c9ba5208811309bdf168b\n    myapp_1 | ===================================================================\n    myapp_1 |\n    myapp_1 | 25-Jan-2019 08:47:18.029 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler [\"http-apr-8888\"]\n    myapp_1 | 25-Jan-2019 08:47:18.034 INFO [main] org.apache.coyote.AbstractProtocol.start Starting ProtocolHandler [\"ajp-apr-8009\"]\n    myapp_1 | 25-Jan-2019 08:47:18.035 INFO [main] org.apache.catalina.startup.Catalina.start Server startup in 1003 ms\n\nAny containerised web application that listens on port 80 should be able to work with Docker Workbench. \n\n\n## Run a simple reverse proxy\n\nDocker Workbench has a simple reverse proxy built-in which can be useful for allowing other network devices on your LAN (other PCs, tablets, phones, etc) to access the applications running inside your Docker Machine VMs.\n\nThe `proxy` command works just like the `up` command and will detect the application and workbench details automatically, giving you a list of addresses that the proxy is listening on;\n\n    $ docker-workbench proxy\n    Starting reverse proxy on port 8080...\n    Listening on:\n\n    http://myapp.192.168.0.10.nip.io:8080/\n\n    Press Ctrl-C to terminate proxy\n\nIn this example another network device would be able to browse to `http://myapp.192.168.0.10.nip.io:8080/` to see the application running.\n\nNote that the default Docker Machine network interface (usually `192.168.99.1`) and other loopback (`127.0.0.1`) or link local (`169.x.x.x`) addresses will not be shown here.\n\nYou can also start the proxy on a port number other than the default `8080` by using the `--port` or `-p` flag:\n\n    $ docker-workbench proxy -p 9001\n\n\n## Advanced Usage\n\nDocker Workbench is basically a utility for easily creating VMs using `docker-machine` and a helper for getting the commands and URLs necessary for running web applications with minimal configuration.\n\nYou can use any `docker-machine` and `docker-compose` command directly, where the \"machine name\" is always the name of parent directory of your applications. Some example commands are;\n\n    docker-machine ls\n    docker-machine inspect workbench\n    docker-machine ssh workbench \n\n    docker-compose build\n    docker-compose config\n\nFor further info view the Docker Machine and Docker Compose reference documentation;\n\n- https://docs.docker.com/machine/reference/\n- https://docs.docker.com/compose/reference/overview/\n\n### Multiple Docker Workbenches\n\nFor situations where you have many applications and you want to run them in separate VMs (e.g. a VM per client, or a VM per group of related applications) you can use `docker-workbench create` to create a workbench from any directory. A simple way of managing your workbenches might be to have a `workbench` folder with several folders inside named by client or application group, and inside each of those a folder for each application. For example;\n\n    workbench\n    ├── clientA\n    │   ├── myapp1\n    │   └── myapp2\n    └── clientB\n        └── anotherapp\n\nIn this scenario you would create two VMs by running `docker-workbench create` from inside the `clientA` and `clientB` folders. Other than this, there is no difference to creating and using just a single VM -- all configuration is done exactly the same as described above.\n\nIt's worth noting that even though your machines in this scenario would be called `clientA` and `clientB`, the shared folder inside the VM which is referred to in your `docker-compose.yml` file will always be named `/workbench` (the shared folder name inside the VM is not named after the VM). A `docker-compose.yml` file for clientB's \"anotherapp\" might look like this;\n\n    anotherapp:\n        image: lucee/lucee:nginx\n        environment:\n            - \"VIRTUAL_HOST=anotherapp.*\"\n        volumes:\n            - \"/workbench/anotherapp/www:/var/www\"\n\nThis also means that you can always run an app inside a Docker Workbench, regardless of what its name is, without modifying the `docker-compose.yml` file.\n\n\n## Troubleshooting\n\n### Destroy and recreate your Docker Workbench\n\nThere are a number of reasons that a Docker VM or your Docker Workbench may get into a bad state, such as invalid networking configurations, a full virtual disk, a missing or accidentally deleted docker-workbench-proxy container, etc. The Docker Workbench can and should be recreated often to update to newer versions of Docker or to resolve issues that can't be easily debugged by the end user.\n\nTo destroy your Docker Workbench and recreate it fresh with the latest version of boot2docker, use `docker-machine` to remove the machine by name (in this case our machine is relative to `/d/workbench` and is called `workbench`), and then `docker-workbench` to create it again;\n\n    $ cd /d/workbench\n    $ docker-machine rm workbench\n    $ docker-workbench create\n\nWithin a few minutes you should be back up and running as normal.\n\n### Keep your CLI Tools up to date\n\nRemember to keep your Docker CLI tools up to date as newer versions of Docker and boot2docker are released. Upgrading to the latest versions on Windows using Chocolatey can be done from an Administrative Command Prompt;\n\n    C:\\\u003e chocolatey upgrade docker\n    C:\\\u003e chocolatey upgrade docker-machine\n    C:\\\u003e chocolatey upgrade docker-compose\n\nOr similarly on MacOS using brew;\n\n    brew upgrade docker\n    brew upgrade docker-machine\n    brew upgrade docker-compose\n\nThis should avoid errors with older Docker client tools trying to connect to newer Docker servers, which may throw an error such as;\n\n\u003e Error checking TLS connection: Error checking and/or regenerating the certs: There was an error validating certificates for host \"192.168.99.100:2376\": x509: certificate has expired or is not yet valid\n\n\u003e ERROR: SSL error: [SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version (_ssl.c:661)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustincarter%2Fdocker-workbench","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjustincarter%2Fdocker-workbench","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjustincarter%2Fdocker-workbench/lists"}