devilbox/docs/getting-started/install-the-devilbox.rst

Install the Devilbox

Important

read_first Ensure you have read this document to understand how this documentation works.

Table of Contents

local

Supported OS

The devilbox runs on all operating systems that provide Docker and Docker Compose.

Requirements

The only requirements for the devilbox is to have Docker and Docker Compose installed, everything else is bundled and provided withing the Docker container. The minimum required versions are listed below:

• Docker: 1.12.0+
• Docker Compose: 1.9.0+

Additionally you will require git in order to clone the devilbox project.

Warning

docker_toolbox Use native Docker and do not use the Docker Toolbox. If you still have to use the Docker Toolbox (e.g. for Windows 7 or older Macs) read up on this section.

Warning

Docker itself requires super user privileges which is granted to a system wide group called docker. After having installed Docker on your system, ensure that your local user is assigned to the docker group. Check this via groups or id command.

install_docker Have a look at this page to help you install Docker for your operating system. install_docker_compose Have a look at this page to help you install Docker Compose for your operating system.

Download the devilbox

The devilbox does not need to be installed. The only thing that is required is its git directory. To download that, open a terminal and copy/paste the following command.

host> git clone https://github.com/cytopia/devilbox

Checkout a different release

You now have the devilbox downloaded at the latest version (git master branch). This is also recommended as it receives bugfixes frequently. If you however want to stay on a stable release, you need to check out s specific git tag.

Lets say you want your devilbox setup to be at release 0.12.1, all you have to do is to check out this specific git tag.

host> cd path/to/devilbox
host> git checkout 0.12.1

Warning

Whenever you check out a different version, make sure that your .env file is up-to-date with the bundled env-example file. Different Devilbox releases might require different settings to be available inside the .env file. Refer to the next section for how to create the .env file.

Create .env file

Inside the cloned devilbox git directory, you will find a file called env-example. This file acts as a template with sane defaults for Docker Compose. In order to use it, it must be copied to a file named .env. (Note the leading dot).

host> cp env-example .env

The .env file does nothing else then providing environment variables for Docker Compose and in this case it is used as the main configuration file for the devilbox by providing all kinds of settings (such as which version to start up).

Docker Compose env file Official Docker documentation about the .env file env_file All available Devilbox .env values and their description

Adjust .env file

To get you started, there are only two variables that need to be adjusted:

• NEW_UID
• NEW_GID

The values for those two variables refer to your local (on your host operating system) user id and group id. To find out what the values are required in your case, issue the following commands on a terminal:

Find your user id

host> id -u

Find your group id

host> id -g

In most cases both values will be 1000, but for the sake of this example, let's assume a value of 1001 for the user id and 1002 for the group id.

Open the .env file with your favorite text editor and adjust those values:

host> vi .env

NEW_UID=1001
NEW_GID=1002

Warning

Make sure that you use the values provided by id -u and id -g.

syncronize_container_permissions Read up more on the general problem of trying to have syncronized permissions between the host system and a running Docker container.

Checklist

1. Docker and Docker Compose are installed at minimum required version
2. Your user is part of the docker group
3. Devilbox is cloned
4. .env file is created
5. User and group id have been set in .env file

That's it, you have finished the first section and have a working Devilbox ready to be started.