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

Install the Devilbox

Important

Ensure you have read and followed the prerequisites

Table of Contents

local

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

• howto_open_terminal_on_mac
• howto_open_terminal_on_win
• checkout-different-devilbox-release

Create .env file

Inside the cloned Devilbox git directory, you will find a file called env-example. This file is the main configuration with sane defaults for Docker Compose. In order to use it, it must be copied to a file named .env. (Pay attention to 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).

* * env_file

Set uid and gid

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

* * howto_find_uid_and_gid_on_mac * howto_find_uid_and_gid_on_win * syncronize_container_permissions

OS specific setup

Linux: SELinux

If you have SELinux enabled, you will also have to adjust the env_mount_options to allow shared mounts among multiple container:

host> vi .env

MOUNT_OPTIONS=,z

* https://github.com/cytopia/devilbox/issues/255 * env_mount_options * *

OSX: Performance

Out of the box, Docker for Mac has some performance issues when it comes to mount directories with a lot of files inside. To mitigate this issue, you can adjust the caching settings for mounted directories.

To do so, you will want to adjust the env_mount_options to allow caching on mounts.

host> vi .env

MOUNT_OPTIONS=,cached

Ensure to read the links below to understand why this problem exists and how the fix works. The Docker documentation will also give you alternative caching options to consider.

* https://github.com/cytopia/devilbox/issues/105#issuecomment-426229921 * https://forums.docker.com/t/file-access-in-mounted-volumes-extremely-slow-cpu-bound/8076/281 * https://docs.docker.com/docker-for-mac/osxfs-caching/#tuning-with-consistent-cached-and-delegated-configurations * env_mount_options

Checklist

1. Devilbox is cloned
2. .env file is created
3. 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.

troubleshooting