1. Install the Devilbox¶

Important

Read first: Ensure you have read this document to understand how this documentation works.

Table of Contents

Supported OS
Requirements
Download the devilbox
- Checkout a different release
Create .env file
Adjust .env file
- Find your user id
- Find your group id
Checklist

1.1. Supported OS ¶

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

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.

1.3. 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

1.3.1. 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.

1.4. 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).

1.5. 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:

1.5.1. Find your user id ¶

host> id -u

1.5.2. 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:

.env¶

host> vi .env

NEW_UID=1001
NEW_GID=1002

Warning

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

1.6. Checklist ¶

Docker and Docker Compose are installed at minimum required version
Your user is part of the docker group
Devilbox is cloned
.env file is created
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.