{"id":13416567,"url":"https://github.com/brikis98/docker-osx-dev","last_synced_at":"2025-03-15T00:31:09.772Z","repository":{"id":32164621,"uuid":"35737822","full_name":"brikis98/docker-osx-dev","owner":"brikis98","description":"A productive development environment with Docker on OS X","archived":true,"fork":false,"pushed_at":"2018-03-04T11:47:17.000Z","size":816,"stargazers_count":1432,"open_issues_count":54,"forks_count":106,"subscribers_count":51,"default_branch":"master","last_synced_at":"2024-07-31T21:57:12.443Z","etag":null,"topics":["boot2docker","developer-tools","docker","osx","rsync"],"latest_commit_sha":null,"homepage":"http://www.ybrikman.com/writing/2015/05/19/docker-osx-dev/","language":"Shell","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/brikis98.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-05-16T19:47:53.000Z","updated_at":"2024-07-16T07:38:43.000Z","dependencies_parsed_at":"2022-09-19T05:01:22.034Z","dependency_job_id":null,"html_url":"https://github.com/brikis98/docker-osx-dev","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brikis98%2Fdocker-osx-dev","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brikis98%2Fdocker-osx-dev/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brikis98%2Fdocker-osx-dev/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brikis98%2Fdocker-osx-dev/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brikis98","download_url":"https://codeload.github.com/brikis98/docker-osx-dev/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243667723,"owners_count":20328032,"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":["boot2docker","developer-tools","docker","osx","rsync"],"created_at":"2024-07-30T21:01:01.051Z","updated_at":"2025-03-15T00:31:09.197Z","avatar_url":"https://github.com/brikis98.png","language":"Shell","readme":"# THIS PROJECT IS NO LONGER MAINTAINED\n\nAs of March 4, 2018, this project is no longer actively maintained. The [Docker for Mac app](https://www.docker.com/docker-mac) \nhas made significant improvements in terms of mounted volume performance and file watching, so `docker-osx-dev` is no longer necessary.\n\n# A productive development environment with Docker on OS X\n\n[Docker](https://www.docker.com/) and [Boot2Docker](http://boot2docker.io/) are\nawesome for running containers on OS X, but if you try to use them to do\niterative development by mounting a source folder from OS X into your Docker \ncontainer, you will run into two major problems:\n\n1. Mounted volumes on VirtualBox use vboxsf, which is *extremely* slow, so\n   compilation and startup times for code in mounted folders is 10-20x slower.\n2. File watching is broken since vboxsf does not trigger the inotify file \n   watching mechanism. The only workaround is to enable polling, which is *much*\n   slower to pick up changes and eats up a lot of resources.\n\nI tried many different solutions (see [Alternatives](#alternatives)) that didn't\nwork until I finally stumbled across one that does:\n[rsync](http://en.wikipedia.org/wiki/Rsync). With rsync, build and compilation \nperformance in mounted folders is on par with native OS X performance and \nstandard file watching mechanisms work properly too. However, setting it up \ncorrectly is a painful process that involves many steps, so to make life \neasier, I've packaged this process up in this **docker-osx-dev** project. \n\nFor more info, check out the blog post [A productive development environment \nwith Docker on OS X](http://www.ybrikman.com/writing/2015/05/19/docker-osx-dev/).\n\n# Status\n\nBeta. A number of developers are successfully using and contributing to\ndocker-osx-dev. It still has some rough edges, but it works well, and makes\nthe docker experience on OS X much better. Give it a try, share your feedback, \nand submit some pull requests!\n\nNote: this project is inherently a temporary workaround. I hope that in the \nfuture, someone will build a better alternative to vboxsf for mounting source \ncode from OS X, and thereby make this entire project obsolete. Until that day \ncomes, I will continue to use the docker-osx-dev scripts to keep myself productive.\n\n# Install\n\nPrerequisite: [HomeBrew](http://brew.sh/) must be installed.\n\nThe `docker-osx-dev` script has an `install` command that can setup your entire \nDocker development environment on OS X, including installing Docker and \nBoot2Docker:\n\n```sh\ncurl -o /usr/local/bin/docker-osx-dev https://raw.githubusercontent.com/brikis98/docker-osx-dev/master/src/docker-osx-dev\nchmod +x /usr/local/bin/docker-osx-dev\ndocker-osx-dev install\n```\n\nFour notes about the `install` command:\n\n1. It is idempotent, so if you have some of the dependencies installed already, \n   it will **not** overwrite them.\n2. When the install completes, it prints out instructions for one `source` \n   command you have to run to pick up important environment variables in your \n   current shell, so make sure not to skip that step!\n3. Once the install completes, you can use the `docker-osx-dev` script to sync \n   files, as described in the next section.\n4. It assumes the user you want to use for development can also run homebrew\n   (eg. write to `/usr/local`). If it doesn't, you need to split the installation\n   in 2 parts: one run as `admin` (the name of the user who can run homebrew),\n   and one as yourself:\n```sh\nsu admin\ndocker-osx-dev install --only-dependencies\nexit\ndocker-osx-dev install --skip-dependencies\n```\n\n# Usage\n\nThe `install` command will install, configure, and run Boot2Docker on your \nsystem, so the only thing left to do is to run the `docker-osx-dev` script and\ntell it what folders to sync. If you run it with no arguments, it will sync the \ncurrent folder to the Boot2Docker VM:\n\n```\n\u003e cd /foo/bar\n\u003e docker-osx-dev\n[INFO] Performing initial sync of paths: /foo/bar\n[INFO] Watching: /foo/bar\n```\n\nAlternatively, you can use the `-s` flag to specify what folders to sync\n(run `docker-osx-dev -h` to see all supported options):\n\n```\n\u003e docker-osx-dev -s /foo/bar\n[INFO] Performing initial sync of paths: /foo/bar\n[INFO] Watching: /foo/bar\n```\n\nNow, in a separate tab, you can run a Docker container and mount the current\nfolder in it using the `-v` parameter. For example, here is how you can fire up \nthe tiny [Alpine Linux image](https://registry.hub.docker.com/u/gliderlabs/alpine/)\nand get a Linux console in seconds:\n\n```\n\u003e cd /foo/bar\n\u003e docker run -v $(pwd):/src -it --rm gliderlabs/alpine:3.1 sh\n/ # cd /src\n/ # echo \"I'm in a $(uname) container and my OS X files are being synced to $(pwd)!\"\nI'm in a Linux container and my OS X files are being synced to /src!\n```\n\nAs you make changes to the files in the `/foo/bar` folder on OS X, using the \ntext editors, IDEs, and tools you're used to, they will be automatically\nsynced to the `/src` folder in the Docker image. Moreover, file watchers should \nwork normally in the Docker container for any framework that supports hot \nreload (e.g. Grunt, SBT, Jekyll) without any need for polling, so you should be \nable to follow a \"make a change and refresh the page\" development model.\n\nIf you are using [Docker Compose](https://docs.docker.com/compose/), \ndocker-osx-dev will automatically sync any folders marked as\n[volumes](https://docs.docker.com/compose/yml/#volumes) in `docker-compose.yml`. \nFor example, let's say you had the following `docker-compose.yml` file:\n\n```yml\nweb:  \n  image: training/webapp\n  volumes:\n    - /foo:/src\n  ports:\n    - \"5000:5000\"\ndb:\n  image: postgres    \n```\n\nFirst, run `docker-osx-dev`:\n\n```\n\u003e docker-osx-dev\n[INFO] Using sync paths from Docker Compose file at docker-compose.yml\n[INFO] Performing initial sync of paths: /foo\n[INFO] Watching: /foo\n```\n\nNotice how it automatically found `/foo` in the `docker-compose.yml` file. \nNow you can start your Docker containers:\n\n```sh\ndocker-compose up\n```\n\nThis will fire up a [Postgres \ndatabase](https://registry.hub.docker.com/u/library/postgres/) and the [training \nwebapp](https://registry.hub.docker.com/u/training/webapp/) (a simple \"Hello, \nWorld\" Python app), mount the `/foo` folder into `/src` in the webapp container, \nand expose port 5000. You can now test this webapp by going to:\n\n```\nhttp://dockerhost:5000\n```\n\nWhen you install docker-osx-dev, it adds an entry to your `/etc/hosts` file so\nthat `http://dockerhost` works as a URL for testing your Docker containers.\n\n# docker-machine support\n\n`docker-machine` support is experimental. You can use it as the way it is used for\n`boot2docker`, but run `docker-machine env` before. So as an example, run as:\n\n```\n\u003e docker-machine create --driver virtualbox \u003cmachine-name\u003e\n\u003e eval \"$(docker-machine env \u003cmachine-name\u003e)\"\n\u003e docker-osx-dev install\n\u003e cd /foo/bar\n\u003e docker-osx-dev\n[INFO] Performing initial sync of paths: /foo/bar\n[INFO] Watching: /foo/bar\n```\n\nIn this case, `docker-osx-dev` will use the machine defined in the `DOCKER_MACHINE_NAME` env var,\ndefined by `docker-machine env`. Alternatively, use the `--machine-name \u003cmachine-name\u003e` argument.\n\nNote: when running `docker-osx-dev` for `boot2docker`, please make sure the env var `DOCKER_MACHINE_NAME`\nis not defined.\n\n\n# How it works\n\nThe `install command` installs all the software you need:\n\n1. [Docker](https://www.docker.com/)\n2. [Boot2Docker](http://boot2docker.io/)\n3. [Docker Compose](https://docs.docker.com/compose/)\n4. [VirtualBox](https://www.virtualbox.org/)\n5. [fswatch](https://github.com/emcrisostomo/fswatch)\n6. The `docker-osx-dev` script which you can use to start/stop file syncing\n\nThe `install` command also:\n\n1. Adds the Docker environment variables to your environment file (e.g. \n   `~/.bash_profile`) so it is available at startup.\n2. Adds an entry to `/etc/hosts` so that `http://dockerhost` works as a valid\n   URL for your docker container for easy testing.\n\nInstead of using VirtualBox shared folders and vboxsf, docker-osx-dev keeps \nfiles in sync by using [fswatch](https://github.com/emcrisostomo/fswatch) to\nwatch for changes and [rsync](http://en.wikipedia.org/wiki/Rsync) to quickly\nsync the files to the Boot2Docker VM. By default, the current source folder \n(i.e. the one you're in when you run `docker-osx-dev`) is synced. If you use \n`docker-compose`, docker-osx-dev will sync any folders marked as \n[volumes](https://docs.docker.com/compose/yml/#volumes). Run `docker-osx-dev -h`\nto see all the other options supported.\n\n# Limitations and known issues\n\nFile syncing is currently one way only. That is, changes you make on OS X\nwill be visible very quickly in the Docker container. However, changes in the\nDocker container will **not** be propagated back to OS X. This isn't a \nproblem for most development scenarios, but time permitting, I'll be looking\ninto using [Unison](http://www.cis.upenn.edu/~bcpierce/unison/) to support\ntwo-way sync. The biggest limitation at the moment is getting a build of \nUnison that will run on the Boot2Docker VM.\n\n# Contributing\n\nContributions are very welcome via pull request. This project is in a very early\nalpha stage and it needs a lot of work. Take a look at the \n[issues](https://github.com/brikis98/docker-osx-dev/issues) for known bugs and\nenhancements, especially the ones marked with the \n[help wanted](https://github.com/brikis98/docker-osx-dev/labels/help%20wanted)\ntag. \n\n## Running the code locally\n\nTo run the local version of the code, just clone the repo and run your local \ncopy of `docker-osx-dev`:\n\n```\n\u003e git clone https://github.com/brikis98/docker-osx-dev.git\n\u003e cd docker-osx-dev\n\u003e ./src/docker-osx-dev\n```\n\n## Running unit tests\n\nTo run the unit tests, install [bats](https://github.com/sstephenson/bats) \n(`brew install bats`) and run the corresponding files in the `test` folder:\n\n```\n\u003e ./test/docker-osx-dev.bats \n ✓ index_of doesn't find match in empty array\n ✓ index_of finds match in 1 item array\n ✓ index_of doesn't find match in 1 item array\n ✓ index_of finds match in 3 item array\n\n[...]\n\n51 tests, 0 failures\n```\n\n## Running integration tests\n\nI started to create integration tests for this project in \n`test/integration-test.sh`, but I hit a wall. The point of the integration test\nwould be to run Boot2Docker in a VM, but most CI providers (e.g. TravisCI and \nCircleCI) already run your build in their own VM, so this would require running \na VM-in-a-VM. As described in [#7](https://github.com/brikis98/docker-osx-dev/issues/7),\nI can't find any way to make this work. If anyone has any ideas, please take a \nlook! \n\n# Alternatives\n\nBelow are some of the other solutions I tried to make Docker productive on OS X\n(I even created a [StackOverflow Discussion](http://stackoverflow.com/questions/30090007/whats-the-right-way-to-setup-a-development-environment-on-os-x-with-docker)\nto find out what other people were doing.) With most of them, file syncing was \nstill too slow to be usable, but they were useful to me to learn more about the\nDocker ecosystem, and perhaps they will be useful for you if docker-osx-dev \ndoesn't work out:\n\n1. [boot2docker-vagrant](https://github.com/blinkreaction/boot2docker-vagrant):\n   Docker, Vagrant, and the ability to choose between NFS, Samba, rsync, and \n   vboxsf for file syncing. A lot of the work in this project inspired \n   docker-osx-dev.\n2. [dinghy](https://github.com/codekitchen/dinghy): Docker + Vagrant + NFS. \n   I found NFS was 2-3x slower than running builds locally, which was much \n   faster than the 10-20x slowness of vboxsf, but still too slow to be usable.\n3. [docker-unison](https://github.com/leighmcculloch/docker-unison): Docker +\n   Unison. The [Unison File Synchronizer](http://www.cis.upenn.edu/~bcpierce/unison/)\n   should be almost as fast as rsync, but I ran into [strange connection \n   errors](https://github.com/leighmcculloch/docker-unison/issues/2) when I \n   tried to use it with Docker.\n4. [Polling in Jekyll](http://salizzar.net/2014/11/06/creating-a-github-jekyll-blog-using-docker/)\n   and [Polling in SBT/Play](http://stackoverflow.com/a/26035919/483528). Some\n   of the file syncing solutions, such as vboxsf and NFS, don't work correctly\n   with file watchers that rely on inotify, so these are a couple examples of \n   how to switch from file watching to polling. Unfortunately, this eats up a\n   fair amount of resources and responds to file changes slower, especially as\n   the project gets larger.\n5. [Hodor](https://github.com/gansbrest/hodor). Uses the [Unison File \n   Synchronizer](http://www.cis.upenn.edu/~bcpierce/unison/) to sync files. I\n   have not had a chance to try this project out yet.\n6. [docker-machine-nfs](https://github.com/adlogix/docker-machine-nfs): Activates NFS \n   for an existing machine.\n\n# License\n\nThis code is released under the MIT License. See LICENSE.txt.\n\n# Changelog\n\n* 06/05/15: merged the `setup.sh` and `docker-osx-dev` scripts together since\n  they share a lot of the same code and bash scripts don't have any easy ways\n  to define modules, download dependencies, etc.\n* 05/25/15: Second version released. Removes Vagrant dependency and uses just\n  rsync + Boot2Docker. If you had installed the first version, you should \n  delete your `Vagrantfile`, delete the old version of \n  `/usr/local/bin/docker-osx-dev`, and re-run the `setup.sh` script.\n* 05/19/15: Initial version released. Uses Vagrant + rsync + Boot2Docker.\n\n","funding_links":[],"categories":["Development with Docker","Dev Tools","Shell","osx"],"sub_categories":["Development Environment"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrikis98%2Fdocker-osx-dev","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrikis98%2Fdocker-osx-dev","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrikis98%2Fdocker-osx-dev/lists"}