Docker on OSX and Windows, as it was meant to be.
Docker is awesome, but it suffers from a few annoying drawbacks:
- Users on Mac OSX or Windows need to go by an intermediary - a virtual machine. This means code synchronisation is a pain, and constant rebuilds are necessary.
- Only certain directories are automatically shared into the vm (e.g.
- Docker Machine requires you to manage multiple machines, but generally you only ever deal with one of them. But we still have to configure with env vars or an annoying
- It is too flexible, resulting in many different ways to achieve 'normal' things. Most people just want to build their app without having to worry about orchestrating containers.
Parity addresses this shortcomings, simplifying Docker for local development.
NOTE: This project, in particular the file syncing problem, will only be partially superceded by Docker when it itself is out of beta. It will also replace items 1-3, leaving Parity to deal with the opinionated setup problem and improving the workflow for development. This is great news for everyone! As Parity is completely plugin-based, you can simple omit plugins (e.g. the
sync plugin) that are superceded by Docker, with no change to your workflow.
Watch Parity in Action:
Simplify Docker for non LXC-native environments (Windows, Mac OSX) by:
- Automatically synchronising code into running containers - no rebuilds!
- Providing a simplified, automatic development and CI workflow for common application types/scenarios
- Automatically configuring Docker (including Docker Machine) for local development
- Ensuring environment parity with CI and Production - all environments use Docker containers
- Allowing customisation to the workflow, or extension of the platform via a plugin interface
Additionally, Parity will not require any other external dependencies, except the Docker ecosystem.
Beta: The first 2 of 4 items are working, with the following features in a beta status:
- Simple installation (
- Code synchronisation into the Docker VM, from any directory, including file pattern exclusions (
- Automatically run a docker compose file via Parity (
- Automatically shell into a running service to look around (
- Automatically attach into a running service to look around (
- Windows support - see the Windows node example. Currently, you need to provide full context paths. We plan on submitting patches to libcompose to move this into upstream and make it simpler.
Download a Parity release and put it somewhere on your
On Mac OSX using Homebrew
brew install https://raw.githubusercontent.com/mefellows/parity/spike/scripts/parity.rb
Download a release
Grab the latest release and put it somewhere on your
Using Go Get
go get github.com/mefellows/parity
Ensure the usual Docker environment variables are exported, then simply run
parity install and follow the prompts.
Creating default host entry
To create a default host entry for http://parity.local (e.g.
/etc/hosts) you can run the Parity installer with the
--dns flag enabled:
sudo -E parity install --dns true
On Windows, run from an elevated PowerShell prompt.
Note: You will need elevated privileges to perform this function.
A typical invocation would look something like this:
parity init # Will create a default, sane parity.yml file parity run"
Parity will then start up your Docker Services (in
./docker-compose.yml) and synchronise files automatically into the Docker Virtual Machine.
By default, Parity will exclude any files containing
tmp or ending with
--config- Path to the configuration file. Defaults to
--verbose- Enable verbose logging.
parity run --help for more detail.
NOTE: This is a MacOSX only feature.
You will need to install XQuartz (
brew install Caskroom/cask/xquartz or see https://xquartz.macosforge.org/trac for details).
First, ensure your X Server is running:
open -a XQuartz
From within a Parity project, you can simply run
parity run and an proxy between Docker and your X Server will automatically be setup for you,
$DISPLAY environment variables in your Docker containers.
If you just want to setup a proxy for another non-Parity managed project, you can run
parity x. This will setup create the Proxy as per above, but
you'll need to manually setup the
$DISPLAY variable. Parity will log to console the environment variable setup. It will look something like
If you are starting a brand new project, you might like to opt for Parity's opinionated workflow, which enforces Docker and continuous delivery best practices.
Parity current has templates for Rails and Node, and you can get started with the
parity setup --template rails --base my-project2
Configuration File format
## The Project Name name: My Awesome Project ## Log Level (0 = Trace, 1 = Debug, 2 = Info, 3 = Warn, 4 = Error, 5 = Fatal) loglevel: 2 ## Plugin configuration. ## ## Parity is essentially a wrapper for Plugins. You can use as much or as little ## as you need. e.g. If you don't need to sync files, simple remove the 'sync' plugin. ## Runtime plugin configuration ## ## Configures the Docker Compose runner run: - name: compose config: composefile: .parity/docker-compose.yml.dev ## File synchronisation plugin configuration. ## ## Configures the file synchronisation Plugin, using Mirror (https://github.com/mefellows/mirror) by default ## This will eventually be superceded by Docker, when native virtualisation comes to OSX + Windows sync: - name: mirror config: verbose: false exclude: - tmp - \.log$ - \.git ## Shell plugin: Enables shelling into an Interactive Docker terminal. ## ## This Plugin allows us to shell into an Interactive terminal via Docker Compose shell: - name: compose ## Docker Registry plugin configuration. ## ## Configures the location images are retrieved from/pushed to. registry: - name: default config: host: parity.local:5000 ## Docker Image Builder plugin configuration. ## ## Configures how images are built and pushed to a Registry. builder: - name: compose config: - image_name: parity-test
Templates exist for the following language/frameworks:
If you create your own (see below), you can have Parity scaffold your project as follows:
parity setup --templateSourceUrl=https://raw.githubusercontent.com/mefellows/parity-my-awesome-lang/master --base my-project2
Creating your own Templates
Parity Templates must adhere to a specific pattern and must be internet accessible. The easiest way to go is creating a public GitHub repository, with the following layout:
├── .parity Contains template configuration files (e.g. DB init scripts etc.) │ ├── TEMPLATE SPECIFIC CONFIGURATION FILES ├── Dockerfile The Base Docker Image. ├── Dockerfile.ci The CI/Build Docker Image. Inherits from Base. ├── Dockerfile.dist The Production Docker Image. Inherits from Base. ├── docker-compose.yml Production Docker Compose setup. ├── docker-compose.yml.dev Local development Docker Compose setup. ├── parity.yml Pre-configured parity.yml file for the Template. └── index.txt A file containing a manifest of all files required in the template.
Additional files may be included, provided that are noted in the Parity Template manifest
/index.txt. By convention these files should lie in the
Template expansion variables
Within the Template files, you can use the following variables using the usual golang
text/template expansion rules e.g.
|Base||The Base docker image||n/a||awesome-proj||yes|
|Ci||CI container image||
|Dist||Prod container image||
All of the below attempt to address the first 2 or 3 goals of this project, but not the fourth (opinionated build and local dev process). Additionally, they all bring in some other dependency and none of them work on Windows.
- https://github.com/brikis98/docker-osx-dev - This is my favourite and much of this project owes to the works of it. It doesn't work on Windows, however, and has a few small pre-requisites. If you're afraid of Parity, consider this!
- https://allysonjulian.com/setting-up-docker-with-xhyve/ and https://github.com/zchee/docker-machine-driver-xhyve - This is even more seamless, using a native containerisation system for MacOSX called xhyve and an experimental Docker driver. Again, this doesn't work on Windows but is very good. One downside is that it needs to allocate the entire drive space, unlike typical vdockerirtualisation applications that will have a dynamically resizable volume.
- https://github.com/nlf/dlite - This aims to solve the top 3 goals of the project. I was never quite able to get this working, but it is quite an interesting project.
- See https://github.com/brikis98/docker-osx-dev#alternatives for others.