# docker guide

## Prerequisites

0. Docker Toolbox (**tested:** 1.9.1)
0. Makefile dependencies (make, ant)
0. `api` directory should be cloned adjacent to this one, e.g. directory structure should look like:
```
workspace
├──orchard
├──api
└──direct_delivery
```

## One-time setup

Before trying the below, you **must** [set up the api repo](https://github.com/theorchard/api/blob/master/docker-guide.md) -- at least the config setup. After successfully bringing up that container, `make clean` in the `api` directory to clean up any lingering containers.

0. `make configs` to create the `docker.properties` **(TODO: deprecate this.)**
0. Edit `docker.properties` with anything missing.
0. `make` to create all the containers for the first time.

For more details on setup, view the [VAPI/OA Docker setup doc](https://docs.google.com/a/theorchard.com/document/d/1JbTKtk-qwLkDfYTMprIKKs2j0migBnbmb9PJQH47FxM/edit?usp=sharing).

## Automatic file syncing

**(WARNING: experimental and Mac OS X only!)**

Docker Machine (VirtualBox) volumes are extremely slow when you have a project with tens of thousands of files. The maintainer of docker-osx-dev has tried a lot of [alternative solutions](https://github.com/brikis98/docker-osx-dev#alternatives) with limited success. Therefore, we'll go ahead and use [docker-osx-dev](https://github.com/brikis98/docker-osx-dev) on Mac OS X (unfortunately no solution for Windows at this time).

Steps:

0. `make clean` to ensure there are no lingering running containers.
0. `make install-dev` to [install docker-osx-dev](https://github.com/brikis98/docker-osx-dev#install).
0. `make watch` to start the file watcher.
0. `make rebuild` in another terminal window, which ups the container.
0. Make changes to files in one of the volume shared folders, and watch them magically propagate into the container!

If you run into problems with any of the above, first of all `brew update` and try again. If that still doesn't work, follow the [install directions](https://github.com/brikis98/docker-osx-dev#install) by hand, `make rebuild && make clean` the container as necessary, and check if manually running `docker-osx-dev` in one terminal, and `docker-compose up -d` in another terminal behave as expected.

## Developing

0. `make rebuild` to recreate containers with the new code.

## Links

0. `make oa` to view OA in your browser at http://oa.192.168.99.100.xip.io
0. `make ws` for Workstation at http://workstation.192.168.99.100.xip.io
0. VAPI, if needed, can be found at http://orchardvapi.192.168.99.100.xip.io

## Troubleshooting
0. If you see a fatal error upon visiting oa (`make oa`) it's very likely that there are some configs out of place. As another example, if VAPI cannot connect to the DB, upon logging in to OA, a cryptic `invalid grant` fatal error will be displayed... Double-check configs are correct in the `api/application/configs` and `orchard/application/configs` directories. Also make sure to run `make replace-configs` in the `api` dir to ensure configs reflect its current `docker.properties`.
0. If the web container is up, you can attach to it by doing `make cli`, which will allow you to check, e.g. `php --version` or `php -m`.
0. We achieve zero-config for the webservers by using xip.io wildcard DNS. Therefore, `docker-machine` needs to be running at its default IP. If it's not, see this [SO answer](http://stackoverflow.com/a/30927897).
0. If you get an error message about port conflict on port 80, it's probably because you left a container up in the `api` directory. Run `make clean` in that directory and try again.
0. See [docker guide from VAPI](https://github.com/theorchard/api/blob/master/docker-guide.md) for more.

Anecdotal fixes to different problem cases: https://docs.google.com/document/d/1rvmIBOXQJFTAAHF0vLFhEOzu8RP2PLwZ-lv1MAL2Or0/edit