From d70879ea9e2a760839b372e88efc3cab4da8b823 Mon Sep 17 00:00:00 2001 From: cytopia Date: Thu, 8 Jun 2017 09:25:03 +0200 Subject: [PATCH] DVL-016 Documentation Intro page --- docs/Configuration.md | 114 --------------- docs/Emails.md | 23 --- docs/Examples.md | 28 ++++ docs/FAQ.md | 22 ++- docs/Info.md | 73 ---------- docs/Intranet.md | 18 --- docs/Logs.md | 58 -------- docs/PHP_Projects.md | 120 ---------------- docs/README.md | 319 +++++++----------------------------------- docs/Updating.md | 68 --------- docs/Usage.md | 63 +++++++-- 11 files changed, 144 insertions(+), 762 deletions(-) delete mode 100644 docs/Configuration.md delete mode 100644 docs/Emails.md create mode 100644 docs/Examples.md delete mode 100644 docs/Info.md delete mode 100644 docs/Intranet.md delete mode 100644 docs/Logs.md delete mode 100644 docs/PHP_Projects.md delete mode 100644 docs/Updating.md diff --git a/docs/Configuration.md b/docs/Configuration.md deleted file mode 100644 index d976893b..00000000 --- a/docs/Configuration.md +++ /dev/null @@ -1,114 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -Configuration | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Configuration - - -### 1. The `.env` file - -All docker-compose configuration is done inside the `.env` file which simply defines key-value variables parsed to `docker-compose.yml`. - -First thing to do after cloning this repository is creating this file from the `env-example`. - -```shell -$ cp env-example .env -``` - -The file itself is well commented and should explain itself. In case anything is unclear leave an issue at GitHub. - -> [What is the `.env` file?](https://docs.docker.com/compose/env-file/) - - -There are a few sections you should be aware off to better understand how it all works. - -#### 1.1 Selecting service versions - -Each service has a `_SERVER` variable with a corresponding version. All existing versions are present in the file and commented out. - -It is important to leave at least one version uncomment, otherwise the start-up will lead to errors. Use the following variable to control which version will be loaded: - -* **`PHP_SERVER`** -* **`HTTPD_SERVER`** -* **`MYSQL_SERVER`** -* **`PGSQL_SERVER`** -* **`REDIS_SERVER`** -* **`MEMCD_SERVER`** - -#### 1.2 Data directories - -There are a few pre-configured data directories to make storage persistent across container restarts: - -* *`HOST_PATH_HTTPD_DATADIR`* -* *`HOST_PATH_MYSQL_DATADIR`* -* *`HOST_PATH_PGSQL_DATADIR`* - -The values by default point to relative directories inside the devilbox repository. You can however also point them to different locations (relative or absolute) - -MySQL and PgSQL data directories will also append their version as a subfolder to the data directories in order to prevent database file corruptions due to different versions and possible incompatabilities between them. - -If you have a MySQL database on your host computer with the same version that your docker container is using, you can also interchangeably use the data dir with you host MySQL version and vice-versa. - -### 2. The `cfg/` directory - -Inside the devilbox root directory you will find a foder called `cfg/`. This will contain subdirectories in the form of `-`. -Those folders will be mounted into the appropriate location into the respective docker container in order to overwrite service configuration. - -Currently only MySQL/MariaDB and PHP/HHVM overrides are supported. - -The folder structure looks like this: -``` -cfg/ - hhvm-latest/ - mariadb-10.0/ - mariadb-10.1/ - mariadb-10.2/ - mariadb-10.3/ - mariadb-5.5/ - mysql-5.5/ - mysql-5.6/ - mysql-5.7/ - mysql-8.0/ - php-fpm-5.4/ - php-fpm-5.5/ - php-fpm-5.6/ - php-fpm-7.0/ - php-fpm-7.1/ -``` - -Each of the folders will contain an example file in the following format: -``` -devilbox-custom.-example -``` - -Only files which have the correct file extensions will be read, all others such as `*.-example` will be ignored. - -#### 2.1 Adding PHP options - - - - ---- - -### Hints - -**A. Can I not just comment out the service in the `.env` file?** - -No, don't do this. This will lead to unexpected behaviour (different versions will be loaded). -The `.env` file allows you to configure the devilbox, but not to start services selectively. At least one version per service must be defined. - -**B. I don't want to start all container. How would I do this?** - -Head over to the **[Usage](Usage.md)** section to get an in-depth explanation about how to start services selectively. diff --git a/docs/Emails.md b/docs/Emails.md deleted file mode 100644 index 017e50e3..00000000 --- a/docs/Emails.md +++ /dev/null @@ -1,23 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -Emails | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Emails - -You can send emails from within your PHP projects without having to worry to accidentally sending them out. - -All emails to whatever recipients are kept inside by a catch-all functionality from within the `php` container (using postfix). - -In order to view the sent emails, use the bundled devilbox intranet and go to the Emails menu. For more information about this see the **[Intranet](Intranet.md)** section. diff --git a/docs/Examples.md b/docs/Examples.md new file mode 100644 index 00000000..deb4baac --- /dev/null +++ b/docs/Examples.md @@ -0,0 +1,28 @@ +# Devilbox Documentation + +| +**Overview** | +**Installing** | +**Updating** | +**Configuration** | +[**Usage**](Usage.md) | +Examples | +**Technical** | +[**FAQ**](FAQ.md) | + +--- + +## Examples + +1. Setup Wordpress +2. Setup Drupal +3. Setup Yii + +--- + +### 1. Setup Wordpress + +### 2. Setup Drupal + +### 3. Setup Yii + diff --git a/docs/FAQ.md b/docs/FAQ.md index 256a2c42..8cf61544 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -1,18 +1,16 @@ # Devilbox Documentation -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -FAQ +| +**Overview** | +**Installing** | +**Updating** | +**Configuration** | +[**Usage**](Usage.md) | +[**Examples**](Examples.md) | +**Technical** | +FAQ | ----- +--- ## FAQ diff --git a/docs/Info.md b/docs/Info.md deleted file mode 100644 index e589d6a4..00000000 --- a/docs/Info.md +++ /dev/null @@ -1,73 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -Info | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Info - - -### Available containers - -It is best to use the hostnames and not to rely on the ip addresses as they might change. In most cases however you can even use `127.0.0.1` or `localhost` (See background section below). - -> E.g.: When you want to setup a MySQL database connection use `mysql` or `127.0.0.1` as the hostname. - -| Container | Container name | Hostname | IP Address | -|-----------------|-----------------|-----------|----------------| -| DNS | bind | bind | 172.16.238.100 | -| PHP / HHVM | php | php | 172.16.238.10 | -| Apache / Nginx | http | http | 172.16.238.11 | -| MySQL / MariaDB | mysql | mysql | 172.16.238.12 | -| PostgreSQL | pgsql | pgsql | 172.16.238.13 | -| Redis | redis | redis | 172.16.238.14 | -| Memcached | memcd | memcd | 172.16.238.15 | -| MongoDB | mongo | mongo | 172.16.238.16 | - -### Background - -#### Background - PHP Container - -The `php` container is the center of all container. Everything happens in there. -This is also the reason it does some more magic than actually required. - -**Remote ports and remote sockets are made available to the `php` container.** - -The PHP container is using [socat](https://linux.die.net/man/1/socat) to -1. forward the remote mysql port `3306` (on the mysql container) to its own `127.0.0.1:3306` -2. forward the remote pgsql port `5432` (on the pgsql container) to its own `127.0.0.1:5432` -3. forward the remote redis port `6379` (on the redis container) to its own `127.0.0.1:6379` -4. forward the remote memcached port `11211` (on the memcd container) to its own `127.0.0.1:11211` -5. forward the remote mongodb port `27017` (on the mongo container) to its own `127.0.0.1:27017` - - -#### Background - Docker Host - -The docker host (your computer) does exactly the same as the `php` container. -1. container mysql port `3306` is exposed to the host on port `127.0.0.1:3306` -2. container pgsql port `5432` is exposed to the host on port `127.0.0.1:5432` -3. container redis port `6379` is exposed to the host on port `127.0.0.1:6379` -3. container memcd port `11211` is exposed to the host on port `127.0.0.1:11211` -3. container mongo port `27017` is exposed to the host on port `127.0.0.1:27017` - -Also the database sockets from the container are mounted into the host. - -#### Background - Benefit of the above - -With the PHP container and the docker host (your computer) behaving the same it is possible to write your php applications like this: -```php --` which will then hold all available log files. - -**Example:** - -``` -devilbox/ - log/ - apache-2.2/ - access_log - error_log - localhost-access.log - localhost-error.log - other-error.log - mariadb-10.3/ - error.log - query.log - slow.log - php-fpm-7.0/ - php-fpm.err - www-access.log - www-error.log -``` - -### Docker logs - -All output that is produced to stdout or stderr by the started service will be available in `docker logs`. In order to view them constantly in a terminal session use: - -```shell -docker-compose logs -f -``` - -Docker logs are currently only being used to display the initial startup including the chosen settings. All other logging is written to file and mounted to the docker host. diff --git a/docs/PHP_Projects.md b/docs/PHP_Projects.md deleted file mode 100644 index 937dbd82..00000000 --- a/docs/PHP_Projects.md +++ /dev/null @@ -1,120 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -[Updating](Updating.md) | -[Info](Info.md) | -PHP Projects | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## PHP Projects - - -### TL;DR - -1. Create folder `${HOST_PATH_HTTPD_DATADIR}/my-project/htdocs` -2. Set `${TLD_SUFFIX}` in the `.env` file (example: `loc`) -2. Expand docker host `/etc/hosts` with `127.0.0.1 my-project.loc` or attach included DNS server to your host and stop worrying about DNS -3. Browse `http://my-project.loc` - - -### Adding projects - -As an example, we are going to add two projects. - -**Prerequisites (dir)** - -For this case let's assume your www root folder points to `~/www`. This means your projects will reside on your host computer in your home directory under www. - -In order to achive this set `HOST_PATH_HTTPD_DATADIR=~/www` in the `.env` file (If this file does not yet exist, copy `env-example` to `.env`). - -`.env`: -``` -... -HOST_PATH_HTTPD_DATADIR=~/www -... -``` - -**Prerequisites (domain suffix)** - -Let's also assume that you have chosen `*.loc` as you projects `TLD_SUFFIX` Domain - -In order to achive this set `TLD_SUFFIX=loc` in the `.env` file (If this file does not yet exist, copy `env-example` to `.env`). - -`.env`: -``` -... -TLD_SUFFIX=loc -... -``` - -**Desired Projects** - -| Project name | Document Root | URL | -|--------------|---------------|-----| -| devilbox | ~/www/devilbox/htdocs | http://devilbox.loc | -| foo.bar | ~/www/foo.bar/htdocs | http://foo.bar.loc | - -`htdocs` can either be a folder or a symlink to a folder. - -**Project: devilbox** - -Setup projects folder and an `index.php` (on your host computer) - -```shell -$ mkdir -p ~/www/devilbox/htdocs -$ vim ~/devilbox/htdocs/index.php -``` - -```php - -``` - -Adjust your local (host computer) `/etc/hosts` and point `devilbox.loc` to your localhost address `127.0.0.1` - -```shell -$ sudo vim /etc/hosts -``` -```shell -127.0.0.1 devilbox.loc -``` - - -**Project: foo.bar** - -Setup projects folder and use existing github project to serve. - -```shell -$ mkdir -p ~/www/foo.bar -$ cd ~/www/foo.bar - -# Use an existing github project as your document root -$ git clone https://github.com// - -# Symlink the project to htdocs -$ ln -s htdocs - -$ ls -l -drwxr-xr-x 4 cytopia 1286676289 136 Oct 30 14:24 / -lrwxr-xr-x 1 cytopia 1286676289 549 Nov 6 15:13 htdocs -> / -``` - - -Adjust your local (host computer) `/etc/hosts` and point `foo.bar.loc` to your localhost address `127.0.0.1` - -```shell -$ sudo vim /etc/hosts -``` -```shell -127.0.0.1 foo.bar.loc -``` - diff --git a/docs/README.md b/docs/README.md index 4ec95cbd..a86cb537 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,292 +1,81 @@ -# Devilbox +# Devilbox Documentation -| **Overview** | **Installing** | **Updating** | **Configuration** | **Usage** | **Technical** | **FAQ** | +| +Overview | +**Installing** | +**Updating** | +**Configuration** | +[**Usage**](Usage.md) | +[**Examples**](Examples.md) | +**Technical** | +[**FAQ**](FAQ.md) | --- +## Overview -### Dockerized LAMP/MEAN stack +1. [Supported Host OS](#1-supported-host-os) +2. [Requirements](#2-requirements) +3. [Docker documentation](#3-docker-documentation) +4. [Devilbox documentation](#4-devilbox-documentation) +5. [Video Tutorials](#5-video-tutorials) -

The devilbox is a modern and highly customisable LAMP and MEAN stack replacement based purely on docker and docker-compose running on all major platforms. It supports an unlimited number of projects for which vhosts and DNS records are created automatically. Email catch-all and popular development tools will be at your service as well.

+--- -Devilbox +### 1. Supported Host OS +The devilbox runs on all major operating systems. Below you can quickly check the recommended docker versions and current issues per OS. -### Supported Host OS +| | ![linux][lin-logo] | ![windows][win-logo] | ![osx][osx-logo] | +|-------------|----------------------|---------------------------|----------------------| +| **Version** | normal | [Docker for Windows][d4w] | [Docker dor Mac][d4m]| +| **Issues** | [here][lin-issues] | [here][win-issues] | [here][osx-issues] | -

Don't worry about switching computers. The devilbox will run on all major operating systems.

+**Note:** There is also the deprecated [Docker Toolbox][dtb] (for Windows and OSX). It is however not recommended to use with the devilbox. -
- Linux support - OSX support - Windows support -
+[win-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png +[lin-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png +[osx-logo]: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png +[d4w]: https://docs.docker.com/docker-for-windows/install/ +[d4m]: https://docs.docker.com/docker-for-mac/install/ +[dtb]: https://docs.docker.com/toolbox/overview/ +[win-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Awindows%22 +[lin-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Alinux%22 +[osx-issues]: https://github.com/cytopia/devilbox/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aopen%20label%3A%22host%3Aosx%22 -### Install, Configure and Start +### 2. Requirements -

Your whole development stack is up and running in a few simple steps.

+* [Docker Engine 1.12.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-21) +* [Docker Compose 1.6.0+](https://docs.docker.com/compose/compose-file/compose-versioning/#version-2) +* On Windows use [Docker for Windows][d4w] (not tested on [Docker Toolbox][dtb]) +* On OSX use [Docker for Mac][d4m] (not tested on [Docker Toolbox][dtb]) -```shell -# Get the soures -$ git clone https://github.com/cytopia/devilbox -$ cd devilbox -# Create and customize the config file -$ cp env-example .env -$ vim .env +### 3. Docker documentation -# Start your daemons -$ docker-compose up -``` +If you have never worked with docker/docker-compose before, you should check up on their documentation to get you started: [docker docs](https://docs.docker.com/). -### Run exactly what you need +### 4. Devilbox documentation -

Choose your required daemons and select a version. Any combination is possible.
This will allow you, to always exactly simulate your production environment locally during development.

+| Topic | Description | +|-------------------------|-------------| +| **Installing** | How to install docker, docker-compose and the devilbox | +| **Updating** | Update best practise | +| **Configuration** | How to configure the devilbox, switch versions (PHP, MySQL, PgSQL, ...) and how to set custom options (php.ini, my.cnf, httpd.conf, ...) | +| **[Usage](Usage.md)** | How to create projects, Email and DNS usage, tools (`composer`, `npm`, `node`, `drush`, ...), entering the container, Log files, Xdebug, ...| +| **[Examples](Examples.md)** | Some project examples for popular CMS/Frameworks. How to setup Wordpress, Drupal, Yii, ... | +| **Technical** | Technical background information | +| **[FAQ](FAQ.md)** | Questions and Troubleshooting | - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ApacheNginxPHPMySQLMariaDBPgSQLRedisMemcachedMongoDB
2.2stable5.45.55.59.12.81.4.212.8
2.4mainline5.55.610.09.23.01.4.223.0
5.65.710.19.33.21.4.233.2
7.08.010.29.4...3.4
7.110.39.51.4.363.5
HHVM9.6latest
+### 5. Video Tutorials -### Run only what you need +Have a look at youtube to see all the features in action. -

You are not forced to load the whole stack everytime. Only bring up what you really need.
It is also possible to add or remove daemons while the stack is already running.

+[![Devilbox setup and workflow](img/devilbox_01-setup-and-workflow.png "devilbox - setup and workflow")](https://www.youtube.com/watch?v=reyZMyt2Zzo) +[![Devilbox email catch-all](img/devilbox_02-email-catch-all.png "devilbox - email catch-all")](https://www.youtube.com/watch?v=e-U-C5WhxGY) -```shell -# Load traditional lamp stack only -$ docker-compose up httpd php mysql - -# Add redis to the running stack -$ docker-compose up redis - -# Stop MySQL from the current stack -$ docker-compose stop mysql -``` - - -### Introduction Videos - -

Head over to youtube for a quick introduction and see for yourself how easily new projects can be created.

- -
- - -
- - -### PHP Modules - -
-

The devilbox is a development stack, so it is made sure that a lot of PHP modules are available out of the box in order to work with many different frameworks. There will however be slight differences between the versions and especially with HHVM. To see the exact bundled modules for each version visit the corresponding docker repositories on Github:

- - PHP - HHVM - -

- PHP 5.4 | - PHP 5.5 | - PHP 5.6 | - PHP 7.0 | - PHP 7.1 | - HHVM -

-

apc, apcu, bcmath, bz2, calendar, Core, ctype, curl, date, dom, ereg, exif, fileinfo, filter, ftp, gd, gettext, gmp, hash, iconv, igbinary, imagick, imap, intl, json, ldap, libxml, magickwand, mbstring, mcrypt, memcache, memcached, mhash, mongodb, msgpack, mysql, mysqli, mysqlnd, openssl, pcntl, pcre, PDO, pdo_mysql, pdo_pgsql, pdo_sqlite, pgsql, phalcon, Phar, posix, pspell, readline, recode, redis, Reflection, session, shmop, SimpleXML, soap, sockets, SPL, sqlite3, standard, sysvmsg, sysvsem, sysvshm, tidy, tokenizer, uploadprogress, wddx, xdebug, xml, xmlreader, xmlrpc, xmlwriter, xsl, Zend OPcache, zip, zlib

-
- - -### Email catch-all - -
- Email catch-all -

The built-in postfix mailserver is configured to automatically intercept all outgoing emails. This is an important measurement during development to make sure not to accidentally send out real emails. Instead you will be able to see all sent emails in the included intranet mail view. See Intranet section below.

-
- - -### Auto-DNS - -
- Auto-DNS -

Creating a new project just requires you to create a new folder on the filesystem. As you probalby don't want to bother with editing your /etc/hosts file everytime, the built-in DNS server will automatically provide the correct DNS records for every project.

-
- - -### Batteries included - -

No need to download external tools. Everything is bundled, up-to-date and available inside the containers.

- -
- Devilbox - Devilbox - Devilbox -
- Devilbox - Devilbox - Devilbox - Devilbox - Devilbox - Devilbox - Devilbox -
- - -### Supported Frameworks and CMS - -

There is nothing special about the devilbox, so any framework or CMS that will work with normal LAMP/MEAN stacks will work here as well. However in order to make double sure, a few popular applications have been explicitly tested.

- -
- CakePHP - Drupal - PhalconPHP - Wordpress - Yii -
- - -### Devilbox Intranet - -

Once the devilbox is up and running, you can visit the bundled intranet on http://localhost.
The intranet is not just a simple dash, it provides many useful tools:

- -
- Container Health | DNS Status | Available vHosts | Emails | Databases | Effective Configuration
- - -
- - -### Security - -

Be aware that the docker service is running with root privileges on your system (like any other webserver for example). The devilbox is using a mix of official docker images and custom images. All integrated containers are available on Github and can be reviewed at any time.

- - -### Up-to-dateness - -

Docker containers are pushed to Docker Hub frequently.
It should be enough for you to pull updated images on a regeular basis.

- -```shell -$ docker-compose pull -``` - -

However, if a new minor version (PHP for example) has just been released and you want to use it right away, you can simply *git clone* the docker repository and rebuild the container. Each container repository contains a shell script for easy building.

- -```shell -# Download PHP 7.1 repository -$ git clone https://github.com/cytopia/docker-php-fpm-7.1 - -# Rebuild the container in order to get the latest minor/patch version -$ cd docker-php-fpm-7.1 -$ ./build/docker-rebuild.sh -``` - - -### Integration Tests - -
- -
- -

In order to make sure everything always runs stable and as expected, the devilbox makes heavy use of integration tests. You can head over to Travis-CI and have a look at stable and nightly builds.

- - -### Contribute - -
-

Contributers are welcome in any way.

- -

First of all, if you like the project, please do star it. Starring is an important measurement to see the number of active users and better allows me to organize my time and effort I can put into this project.

- -

You can also get actively involved. Do clone the project and start improving whatever you think is useful. There is quite a lot todo and planned. If you like to contribute, view CONTRIBUTING.md and ROADMAP.

- -

Major contributors will be credited within the intranet and on the github page.

-
- - -### License - -
-

MIT License

-

Copyright (c) 2016 cytopia

-
diff --git a/docs/Updating.md b/docs/Updating.md deleted file mode 100644 index aeb59d97..00000000 --- a/docs/Updating.md +++ /dev/null @@ -1,68 +0,0 @@ -# Devilbox Documentation - -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | -[Usage](Usage.md) | -Updating | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) - ----- - -## Updating - -### Tags vs Branches - -The devilbox git repository offers two types of setups. - -1. Git `tags` for stable release -2. The `master` branch with the latest features - - -### Git tags - -Each new devilbox release is tagged in git and bound to tagged docker images. -Updating only involves to check out the latest tag and make sure to stop and remmove your containers prior starting them up again. Latest docker images will be pulled automatically as their docker tag number will also change between releases. - -Additionally you will also have compare `env-example` against your current `.env` file and in case of differences apply them. - -```shell -# Update source -$ git fetch --all -$ git checkout - -# Stop and remove your container -$ docker-compose stop -$ docker-compose rm - -# Check for config file changes -$ vimdiff .env env-example -``` - -Currently releases are not that frequent, so you might be better of with the `master` branch. - -### Git master branch - -The `master` branch does not use tagged docker images, but `latest`. So once you git pull you should also pull the latest docker images. - - -```shell -# Update source -$ git fetch --all -$ git pull origin master - -# Stop and remove your container -$ docker-compose stop -$ docker-compose rm - -# Pull latest docker images -$ docker-compose pull - -# Check for config file changes -$ vimdiff .env env-example -``` diff --git a/docs/Usage.md b/docs/Usage.md index f6a58c68..30799069 100644 --- a/docs/Usage.md +++ b/docs/Usage.md @@ -1,21 +1,62 @@ # Devilbox Documentation -[Home](https://github.com/cytopia/devilbox) | -[Overview](README.md) | -[Configuration](Configuration.md) | +| +**Overview** | +**Installing** | +**Updating** | +**Configuration** | Usage | -[Updating](Updating.md) | -[Info](Info.md) | -[PHP Projects](PHP_Projects.md) | -[Emails](Emails.md) | -[Logs](Logs.md) | -[Intranet](Intranet.md) | -[FAQ](FAQ.md) +[**Examples**](Examples.md) | +**Technical** | +[**FAQ**](FAQ.md) | ----- +--- ## Usage +1. [Start and Stop](#1-start-and-stop) + 1. [Normal Start](#1-1-normal-start) + 2. [Background Start](#) + 3. [Selective Start](#) + 4. [Normal Stop](#) + 5. [Selective Stop](#) + 6. [Attach/Detach during run-time](#) +2. [Work inside the PHP container](#) + 1. [As devilbox user](#) + 2. [As root user](#) + 3. [Available tools](#) + 4. [Available URLs](#) +3. [Creating Projects](#) + 1. Creating projects on the docker host + 2. Creating projects from within the PHP container +4. [DNS](#) + 1. [/etc/hosts](#) + 2. [Auto-DNS](#) +5. [Intranet](#) +6. [Emails](#) +7. [Log files](#) + +--- + +### 1. Start and Stop + +Starting and stopping containers is done via docker-compose. If you have never worked with it before, have a look at their documentation for an [overview](https://docs.docker.com/compose/reference/overview/), [up](https://docs.docker.com/compose/reference/up/) and [stop](https://docs.docker.com/compose/reference/stop/) + +#### 1.1 Normal Start + +The normal start will bring up all container defined in *docker-compose.yml* and will stay in forground making it possible to stop them via Ctrl+c. + +```shell +$ docker-compose up +``` + +#### 1.2 Background Start +#### 1.3 Selective Start +#### 1.4 Normal Stop +#### 1.5 Selective stop +#### 1.6 Attach/Detach during run-time +### 2. Creating Projects + This section is about how to start, stop, view and enter (all or a selection of some) containers. If you want to know how to choose the container type version (e.g. which mysql version or which php version) refer to the **[Configuration](Configuration.md)** section. **Convention:** The terms *container* and *service* are used interchangeably.