Skip to content

Latest commit

 

History

History
211 lines (146 loc) · 7.69 KB

README.md

File metadata and controls

211 lines (146 loc) · 7.69 KB
Raw

Jetdocker

Jetdocker

jetdocker is a wrapper around docker compose, especially opinionated for PHP developpement, but not only.

Some of the features are :

  • can run several docker compose projects, bind automatically to free ports if some try to bind on the same, using a reverse-http-proxy
  • smooth database restoration, can use Search and Replace DB automatically
  • SSL-TLS auto-signed certificate automatically created and configured, in order to test on https
  • xdebug integration
  • phpmyadmin integration

Getting Started

Prerequisites

Disclaimer: Jetdocker works on macOS and Linux.

  • Unix-like operating system (macOS or Linux)
  • bash 4
  • docker and docker compose should be installed, also compatible with docker-compose
  • php and xdebug PHP extension
  • symfony should be installed
  • git should be installed
  • await should be installed

Install bash4

On macOSX bash3 is installed by default, but you can install bash4

brew install bash
echo '/usr/local/bin/bash' | sudo tee -a /etc/shells

Install php and xdebug extension

On macOSX

brew install php
pecl install xdebug

Then create the file ${PHP_INSTALL_PATH}/etc/php/8.0/conf.d/ext-xdebug.ini where ${PHP_INSTALL_PATH} is /usr/local or /opt/homebrew (following your architecture, see https://docs.brew.sh/Installation) with the following content:

[xdebug]
;zend_extension="/usr/local/lib/php/pecl/20200930/xdebug.so"
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.var_display_max_depth=15
xdebug.idekey=PHPSTORM

Install symfony binary

See https://symfony.com/download

Install await

On linux

sudo curl -s -f -L -o /usr/local/bin/await https://github.com/betalo-sweden/await/releases/download/v1.2.0/await-linux-amd64
sudo chmod +x /usr/local/bin/await

On macOSX

curl -f -L -o /usr/local/bin/await https://github.com/betalo-sweden/await/releases/download/v1.2.0/await-darwin-amd64
chmod +x /usr/local/bin/await

Basic Installation

jetdocker is installed by running one of the following commands in your terminal. You can install this via the command-line with curl.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/jetpulp/jetdocker/master/tools/install.sh)"

Basic Usage

In order to use jetdocker in your project you need a docker directory, containing all the jetdocker config files. docker is the default path, you can specify a different one with the jetdocker -c configPath option.

You can find some examples of docker config directory in the examples directory of this repository, "ready to use" for wordpress, magento or symfony projects.

The bare minimum is a compose.yaml ( or compose.yml, docker-compose.yaml, docker-compose.yml) and a env.sh file in this directory.

The env.sh file is required in order to define some environement variables on each project

  • COMPOSE_PROJECT_NAME : (required) a prefix used for naming containers and volumes
  • JETDOCKER_UP_DEFAULT_SERVICE : (optional, default=web) docker compose service used by jetdocker up
  • JETDOCKER_DB_DEFAULT_SERVICE : (optional, default=db) docker compose service used for database restoration
  • JETDOCKER_TERM_DEFAULT_SERVICE : (optional) docker compose service used by jetdocker term
  • DB_RESTORE_TIMEOUT : (optional, default=3m0s) database restoration timeout
  • SERVER_NAME : (required) hostname
  • VIRTUAL_HOST : (required) list of hostnames, separated by comma
  • MYSQL_DATABASE : (optional) name of the database

Usually SERVER_NAME is constructed based on an other env var : JETDOCKER_DOMAIN_NAME, jetdocker set it as default to localhost.tv (see http://localhost.tv), for example with SERVER_NAME=project.$JETDOCKER_DOMAIN_NAME, project.localhost.tv will resolve on 127.0.0.1.

JETDOCKER_DOMAIN_NAME can be modified in ~/.jetdockerrc, for example: JETDOCKER_DOMAIN_NAME=192.168.0.10.xip.io, xip.io will resolve *.192.168.0.10.xip.io on 192.168.0.10, you could then test with a mobile device on your local server which is on 192.168.0.10 on your local LAN.

Some hook functions can be added or overridden in env.sh, here some examples :

Up::InstallBeforeStartUp()
{
    Log "Up::InstallBeforeStartUp : add this function in env.sh to export env var in some config file"  
    Up::Install ## run make install under the hood
}
Up::InstallAfterStartUp()
{
    Log "Up::InstallAfterStartUp : add this function in env.sh to export env var in some config file"  
    Up::Install ## run make install under the hood
}
Up::ExportEnv()
{
    Log "Up::ExportEnv : add this function in env.sh to export env var in some config file"  
}
Up::StartLocalApp()
{
    Log "Up::StartLocalApp : add this function in env.sh to start a local app"
}

The main usage of jetdocker is to run a docker compose config :

jetdocker up

Some usefull option of jetdocker up are :

  • jetdocker up -x : Enable xdebug in PHP container
  • jetdocker up -o : Open browser after start on the $SERVER_NAME url
  • jetdocker up -d : Delete data docker volumes before start, forcing it to restore

See all other available commands and options

jetdocker --help

Advanced Usage

Here are the different commands

  • up : Start docker compose after initializing context (databases, ports, proxy, etc... )
  • term : Open a shell terminal into one of docker compose service
  • compose : Run a docker compose command (alias for docker compose run --rm)
  • free-disk-space :Free disk space utility
  • update : Update jetdocker to the latest version
  • search-replace-db : Run Search Replace DB in a container
  • phpmyadmin : Start/Restart a PhpMyAdmin container connecting to all running MySQL containers

SSL/TLS Certificate

On first start of jetdocker up, jetdocker will generate a SSL/TLS certificate, signed by the ./cacerts/jetdockerRootCA.crt Root CA certificate, for all the $JETDOCKER_DOMAIN_NAME subdomains (default is *.localhost.tv). This certificate is stored in a docker volume named jetdocker-ssl-certificate, and this volume is mounted in the nginx-proxy container, and used by nginx.

In order to avoid the browser alert due to an unknown CA, you should import the ./cacerts/jetdockerRootCA.crt in your browsers as a new CA :

If you change your $JETDOCKER_DOMAIN_NAME, you will have to delete your jetdocker-ssl-certificate volume to force jetdocker to recreate it : docker volume rm jetdocker-ssl-certificate.

Getting Updates

By default, an automatic update is done every day.

Contributing

Feel free to send PR, and open issues.

Road Map

  • a "create" command which copy a template of docker config files

Acknowledgement

Disclaimer: Jetdocker is standing on the shoulder of giants.

Thank's to

Follow Us

We're on the social media.

  • @jetpulp on Twitter. You should follow it.

License

Jetdocker is released under the MIT license.

About JETPULP

JETPULP

Jetdocker was developped by the team at JETPULP, a digital agency.