Docker Devbox is a set of tools build on top of Docker that automates environments setup for web applications, from development to production.
It relies on ddb, a command line tool that provides features to generate, activate and adjust configuration files based on a single overridable and extendable configuration, while enhancing the developer experience and reducing manual operations.
- Give the developer a clear and native experience, but use docker containers under the hood.
- Isolate each project, but share common patterns and tools.
- Keep control on how containers are built, by keeping
Dockerfile
anddocker-compose.yml
visible and editable. - Deploy to stage and production environment with no change to the project source code.
- Workaround usual caveats of docker on development environments.
- Activate the project environment automatically when cd into the project folder (SmartCD).
- Access application through
.test
development domain name (Traefik). - Generate trusted SSL certificate automatically through a development certificate authority (Cloudflare CFSSL or mkcert)
- Install CA certificates automatically to docker images, to support containers SSL inter-communication and SSL Corporate proxies like Palo Alto SSL Inbound Inspection .
- Brings project containers commands to shell
PATH
and bind current working directory, commands behave as if there were installed right on the host (For example,composer install
andnpm install
will just work as usual,psql
andmysql
can connect to the database). - Fix usual permission issues by automating local volume directory creation and fixuid integration.
- Configure each target environment (
dev
,stage
,prod
) with environment variables only. - Introduce environment variables into configuration files with a template engine (Mo - Mustache Templates in Bash).
- Enable configuration files matching the active environment with simple symlinks creation automation (mo pure bash templating engine).
- Switch to a real public domain name with no pain (Traefik and Let's Encrypt).
- Access application from a private network remotely through an automated SSH tunnel (ngrok , Serveo or ssi.sh)
Docker Devbox runs natively on any Linux only, but Windows and MacOS users may use docker-devbox-vagrant to run it inside a Vagrant managed VirtualBox VM based on Ubuntu Server.
- Docker >= 18.09.6
- Docker compose plugin >= 2
- GNU Bash >= 4.0
- curl
curl -L https://github.com/inetum-orleans/docker-devbox/raw/master/installer | bash
This will install everything required for Docker Devbox, but docker, docker compose and bash should be installed manually before.
Docker Devbox will install Traefik in a docker container and binds tcp/80
,tcp/443
to host,
so those ports should be available.
Port tcp/7780
should also be available for CFSSL container (local certificate authority service).
Installation script may ask for sudo password to install some dependencies, like curl, git and make.
To access application through .test
development domain name, you have to setup your system for those domains to be
resolved as docker host IP.
On Linux, dnsmasq can be used for this purpose.
On Windows, Acrylic DNS proxy can be used for this purpose.
- Ubuntu Server (without NetworkManager)
sudo apt-get install -y dnsmasq
DOCKER_HOST_IP=$(ip -4 addr show docker0 | grep -Po 'inet \K[\d.]+')
sudo sh -c "echo address=/.test/$DOCKER_HOST_IP>/etc/dnsmasq.d/test-domain-to-docker-host-ip"
sudo service dnsmasq restart
- Ubuntu Desktop (with NetworkManager)
NetworkManager from desktop brings it's own dnsmasq daemon.
sudo mv /etc/resolv.conf /etc/resolve.conf.bak
sudo ln -s /var/run/NetworkManager/resolv.conf /etc/resolv.conf
sudo sh -c 'cat << EOF > /etc/NetworkManager/conf.d/use-dnsmasq.conf
[main]
dns=dnsmasq
EOF'
sudo sh -c 'cat << EOF > /etc/NetworkManager/dnsmasq.d/test-domain-to-docker-host-ip
address=/.test/$(ip -4 addr show docker0 | grep -Po "inet \K[\d.]+")
EOF'
sudo service NetworkManager restart
Download Acrylic DNS proxy for Windows, and perform installation.
Then open Acrylic UI and configure the Host configuration with such entry
192.168.1.100 *.test
The IP address should match the IP of the docker engine.
Docker Devbox automatically generates development certificate for HTTPS support, but you need to register the local CA certificate using mkcert.
Run the following commands from docker devbox shell.
# This dependency is required to support Chrome and Firefox.
sudo apt-get install libnss3-tools
# Uninstall any previous CA cert
mkcert -uninstall
# Move to cfssl container directory
cd ~/.docker-devbox/cfssl
# Replace default mkcert key/pair with CFSSL public key.
rm -Rf $(mkcert -CAROOT) && mkdir -p $(mkcert -CAROOT)
docker compose cp intermediate:/etc/cfssl/ca.pem $(mkcert -CAROOT)/rootCA.pem
# Install CFSSL CA Certificate with mkcert.
mkcert -install
On Windows, you should install the CA certificate inside the VM where docker-devbox is installed with the previous linux procedure, but you should also install the CA certificate on your host, for browser to aknowlegdge the development certificates.
-
Download mkcert for Windows, and set
CAROOT
environment variable to some directory, likeC:\mkcert-ca
. -
Extract the CFSSL ca certificate from docker with the following command
# Inside docker-devbox shell
cd ~/.docker-devbox/cfssl
docker compose cp intermediate:/etc/cfssl/ca.pem ../certs/mkcert-ca/rootCA.pem
-
Copy
~/.docker-devbox/certs/mkcert-ca/rootCA.pem
to the host, insideCAROOT
directory. -
Close all
cmd.exe
, and open a new one to check thatCAROOT
environment variable is defined.
# This should output CAROOT environment variable
mkcert -CAROOT
- Install CA certificate
mkcert -install
Environment variables available for installer script:
DOCKER_DEVBOX_MINIMAL
: Clone docker-devbox repository and create reverse-proxy network only.DOCKER_DEVBOX_DDB_VERSION
: Install a specific version of ddb (ex:v2.0.1
). When unset, gets the latest versionDOCKER_DEVBOX_DISABLE_SMARTCD
: Disable SmartCD.DOCKER_DEVBOX_DISABLE_CFSSL
: Disable CFSSL.DOCKER_DEVBOX_DISABLE_PORTAINER
: Disable portainer.DOCKER_DEVBOX_DISABLE_REVERSE_PROXY
: Disable reverse-proxy feature.DOCKER_DEVBOX_DISABLE_UPDATE
: Disable update of docker-devbox. This may be useful when running installer right from local repository.DOCKER_DEVBOX_CI
: Equivalent toDOCKER_DEVBOX_MINIMAL
andDOCKER_DEVBOX_DISABLE_OPTIONAL_DEPENDENCIES
, recommanded for CI.DOCKER_DEVBOX_BRANCH
: Use a custom docker-devbox branch.DOCKER_DEVBOX_LEGACY
: Install legacy bash docker-devbox scripts that were used before ddb.DOCKER_DEVBOX_DDB_ASSET_NAME
: Custom ddb release asset name to install ddb. Set to "ddb-linux-older-glibc" to install on older linux distributions, like Ubuntu 16.04. You should also add this value tocore.release_asset_name
in ddb configuration to makeself-update
command download this asset.DOCKER_DEVBOX_CURL_OPTS_GITHUB_API
: Additional curl options to pass when accessing github api. You can set this variable to-u <username:token>
using a Github Personnal Access Token if you encounter 403 errors due to rate limiting.DOCKER_DEVBOX_SKIP_DOCKER_CHECKS
: Force installation even ifdocker
ordocker compose
binaries are unavailable.
Environment variables can be set right before bash invocation in the installer one-liner.
curl -L https://github.com/inetum-orleans/docker-devbox/raw/master/installer | \
DOCKER_DEVBOX_CI=1 \
bash
Use Yeoman with inetum-orleans/generator-docker-devbox generator to scaffold a new project from interactive questions.
As an alternative, you may grab a sample project from inetum-orleans/docker-devbox-examples repository, and edit to fit your needs.
If you need to access some commands from a docker-devbox project globally from any other directory inside your host, you may run the following command from the project directory.
docker-devbox bin global
This bring the project commands from projects .bin
directory into the current user ~/bin
directory, and configures
them for an external usage. This directory is in the user PATH
by default on most linux distribution, but you may
have to restart the shell at the first time.
To remove global commands from a project, run the following command from the project directory.
docker-devbox bin local
Please read MIGRATION.md to migration machine and projects from previous version.