General prerequisites

Node.js

Install Node.js version >= 6

Yeoman + Generator

Install Yeoman + Generator-phovea with the following command:

sudo npm install -g yo https://github.com/phovea/generator-phovea

Docker and Docker Compose

Docker Toolbox (if needed)

When using the Docker Toolbox install the workspace under C:\Users\... because otherwise the VM cannot access the host’s folder structure. Furthermore the host’s port 127.0.0.1:9000 must manually be forwarded to the guest’s port 9000. See Using Docker Toolbox (for Windows version < 10 Pro + HyperV).

Docker Toolbox + Proxy

If the computer on which the workspace should be created is behind a proxy server and Docker Toolbox is used, store them inside the Docker Toolbox start script under C:\Program Files\Docker Toolbox\start.sh:

export HTTP_PROXY="http://hostname:port/"
export HTTPS_PROXY="http://hostname:port/"
docker-machine restart default

Using Docker Toolbox (for Windows version lower than 10 Pro + HyperV)

Versions of Windows < 10 Pro + HyperV support, require Docker Toolbox to be installed. In this setup Docker will run inside a virtual machine using VirtualBox, which will be installed by Docker Toolbox. By default, only Windows C:\Users\... directory is shared with the virtual machine, therefore has the workspace to be created somewhere inside the Users directory, otherwise the installation will fail.
Another important step is to manually forward the host’s port 9000 (which is the port the API Docker container listens to) to the guest’s port 9000. This is done with the following steps:

  • Open the VirtualBox
  • Settings
  • Network
  • In Adapter 1 (selected by default) click Advanced
  • Port Forwarding
  • Add a new rule with the following settings:
    • Protocol: TCP
    • Host IP: 127.0.0.1
    • Host Port: 9000
    • Guest IP: leave empty
    • Guest Port: 9000
    • Confirm

The virtual machine is started automatically when the Docker Toolbox shell is opened. The virtual machine is by default called default. The virtual machine can be stopped again with the following command (with the name of the VM as the last parameter):

docker-machine stop default

To restart the VM execute:

docker-machine restart default

When using the Docker Toolbox the directory to place the workspace in must be in C:\Users\... and the port 9000 needs to be forwarded manually.

Running Docker behind a Proxy Server

When installing the workspace from a company network with a proxy server the proxy settings for Docker need to be stored in two places. First, Docker Toolbox (if used) needs to know the proxy settings such that the VM can access the Internet and download the required packages. To add them, open C:\Program Files\Docker Toolbox\start.sh. This file needs to be changed to contain the following two lines:

export HTTP_PROXY=yourproxylocation
export HTTPS_PROXY=yourproxylocation

After adding the proxy settings to the start script, the VM needs to be restarted.

The second location to store the proxy settings is the docker-compose-patch.yml file, which is created after setting up the workspace (see Setting up the workspace first) in the root folder. Despite other configuration it contains proxy settings for the API and the server service, which look like in the following listing:

...
environment:
http_proxy=yourproxylocation
https_proxy=yourproxylocation
...
```## Using Docker Toolbox (for Windows version lower than 10 Pro + HyperV)
Versions of Windows < 10 Pro + HyperV support, require Docker Toolbox to be installed. In this setup Docker will run inside a virtual machine using VirtualBox, which will be installed by Docker Toolbox. By default, only Windows `C:\Users\...` directory is shared with the virtual machine, therefore has the workspace to be created somewhere inside the Users directory, otherwise the installation will fail.
Another important step is to manually forward the host’s port 9000 (which is the port the API Docker container listens to) to the guest’s port 9000. This is done with the following steps:
- Open the VirtualBox
- Settings
- Network
- In Adapter 1 (selected by default) click Advanced
- Port Forwarding
- Add a new rule with the following settings:
  - Protocol: TCP
  - Host IP: 127.0.0.1
  - Host Port: 9000
  - Guest IP: leave empty
  - Guest Port: 9000
  - Confirm

The virtual machine is started automatically when the Docker Toolbox shell is opened. The virtual machine is by default called `default`. The virtual machine can be stopped again with the following command (with the name of the VM as the last parameter):

docker-machine stop default


To restart the VM execute:

docker-machine restart default



When using the Docker Toolbox the directory to place the workspace in must be in `C:\Users\...` and the port 9000 needs to be forwarded manually.

## Running Docker behind a Proxy Server
When installing the workspace from a company network with a proxy server the proxy settings for Docker need to be stored in two places. First, Docker Toolbox (if used) needs to know the proxy settings such that the VM can access the Internet and download the required packages. To add them, open `C:\Program Files\Docker Toolbox\start.sh`. This file needs to be changed to contain the following two lines:

export HTTP_PROXY=yourproxylocation
export HTTPS_PROXY=yourproxylocation


After adding the proxy settings to the start script, the VM needs to be restarted.

The second location to store the proxy settings is the `docker-compose-patch.yml` file, which is created after setting up the workspace (see [Setting up the workspace first](#setting-up-the-workspace)) in the root folder. Despite other configuration it contains proxy settings for the API and the server service, which look like in the following listing:

...
environment:
http_proxy=yourproxylocation
https_proxy=yourproxylocation
...


So both occurrences of the environment proxy settings need to be changed. Afterwards the workspace needs to be updated by using the generator’s update command:

yo phovea:update


If the containers are already running in background mode (with the `-d` option) restart them by running:

docker-compose restart


Or, if the containers are running in foreground mode restart by hitting CTRL-C and execute:

docker-compose up

So both occurrences of the environment proxy settings need to be changed. Afterwards the workspace needs to be updated by using the generator’s update command:

yo phovea:update

If the containers are already running in background mode (with the -d option) restart them by running:

docker-compose restart

Or, if the containers are running in foreground mode restart by hitting CTRL-C and execute:

docker-compose up


# Conclusion
Lessons learned:
- How to configure proxy settings
- How to use the Docker Toolbox when using an Operating System Docker does not run natively on