ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-06-18 15:18:14 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Documentation restructuring

Browse Source
This commit is contained in:
cytopia
2018-07-03 15:47:58 +02:00
parent 0121371048
commit acab8b346e
169 changed files with 2211 additions and 865 deletions
Download Patch File Download Diff File Expand all files Collapse all files

246
docs/getting-started/best-practice.rst
View File

@ -1,246 +0,0 @@
.. _getting_started_best_practice:
*************
Best practice
*************
If you have already read all documents in the Getting started guide, you should be ready to fully
operate the Devilbox. This section builds on top of that and gives you some best-practices as well
as tips and tricks.
**Table of Contents**
.. contents:: :local:
Move data out of Devilbox directory
===================================
One thing you should take into serious consideration is to move data such as your projects as well
as persistent data of databases out of the Devilbox git directory.
The Devilbox git directory should be something that can be safely deleted and re-created without
having to worry about loosing any project data. There could also be the case that you have a
dedicated hard-disk to store your projects or you have your own idea about a directory structure
where you want to store your projects.
Projects
--------
So let's assume all of your projects are already in place under ``/home/user/workspace/web/``. Now
you decide to use the Devilbox, but still want to keep your projects where they are at the moment.
All you have to to is to adjust the path of :ref:`env_httpd_datadir` in the ``.env`` file.
.. code-block:: bash
# Navigate to Devilbox git directory
host> cd path/to/devilbox
# Open the .env file with your favourite editor
host> vim .env
Now Adjust the value of :ref:`env_httpd_datadir`
.. code-block:: bash
:caption: .env
:emphasize-lines: 1
HOST_PATH_HTTPD_DATADIR=/home/user/workspace/web
That's it, whenever you start up the Devilbox ``/home/user/workspace/web/`` will be mounted into
the PHP and the web server container into ``/shared/httpd/``.
Databases
---------
Moving your projects out of the Devilbox git directory is one step, you still need to take care
about persistent data of all available databases as well.
Let's assume you desired location for database storage is at ``/home/user/workspace/db/``.
MySQL
^^^^^
All you have to to is to adjust the path of :ref:`env_mysql_datadir` in the ``.env`` file.
.. code-block:: bash
# Navigate to Devilbox git directory
host> cd path/to/devilbox
# Open the .env file with your favourite editor
host> vim .env
Now Adjust the value of :ref:`env_mysql_datadir`
.. code-block:: bash
:caption: .env
:emphasize-lines: 1
HOST_PATH_MYSQL_DATADIR=/home/user/workspace/db/mysql
That's it, whenever you start up the Devilbox ``/home/user/workspace/db/mysql/`` will be mounted
into the MySQL container.
PostgreSQL
^^^^^^^^^^
All you have to to is to adjust the path of :ref:`env_pgsql_datadir` in the ``.env`` file.
.. code-block:: bash
# Navigate to Devilbox git directory
host> cd path/to/devilbox
# Open the .env file with your favourite editor
host> vim .env
Now Adjust the value of :ref:`env_pgsql_datadir`
.. code-block:: bash
:caption: .env
:emphasize-lines: 1
HOST_PATH_PGSQL_DATADIR=/home/user/workspace/db/pgsql
That's it, whenever you start up the Devilbox ``/home/user/workspace/db/pqsql/`` will be mounted
into the PostgreSQL container.
MongoDB
^^^^^^^
All you have to to is to adjust the path of :ref:`env_mongo_datadir` in the ``.env`` file.
.. code-block:: bash
# Navigate to Devilbox git directory
host> cd path/to/devilbox
# Open the .env file with your favourite editor
host> vim .env
Now Adjust the value of :ref:`env_mongo_datadir`
.. code-block:: bash
:caption: .env
:emphasize-lines: 1
HOST_PATH_MONGO_DATADIR=/home/user/workspace/db/mongo
That's it, whenever you start up the Devilbox ``/home/user/workspace/db/mongo/`` will be mounted
into the MongoDB container.
Version control ``.env`` file
-----------------------------
The ``.env`` file is ignored by git, because this is *your* file to customize and it should be
*your* responsibility to make sure to backup or version controlled.
One concept you can apply here is to have a separate **dotfiles** git repository.
This is a repository that holds all of your configuration files such as vim, bash, zsh, xinit
and many more. Those files are usually stored inside this repository and then symlinked to the
correct location. By having all configuration files in one place, you can see and track changes
easily as well as bein able to jump back to previous configurations.
In case of the Devilbox ``.env`` file, just store this file in your repository and symlink it to
the Devilbox git directiry. This way you make sure that you keep your file, even when the Devilbox
git directory is deleted and you also have a means of keeping track about changes you made.
You could also go further and have several ``.env`` files available somewhere. Each of those files
holds different configurations e.g. for different projects or customers.
* ``env-customer1``
* ``env-php55``
* ``env-project3``
You would then simply symlink one of those files to the Devilbox git directory.
Version control service config files
------------------------------------
.. todo:: This will require some changes on the Devilbox and will be implemented shortly.
* Symlink and have your own git directory
* Separate data partition, backups
PHP project hostname settings
=============================
When configuring your PHP projects to use MySQL, PostgreSQL, Redis, Mongo and other services,
make sure to set the hostname of each of those services to ``127.0.0.1``.
**Why is that?**
The PHP container port-forwards each service port to its own listen address on ``127.0.0.1``.
The Devilbox also exposes each of those service ports to the host operating system on ``127.0.0.1``.
This allows you to keep your project configuration unchanged and have the same behaviour inside the
PHP container and on your host operating system.
.. important::
Do not mix up ``localhost`` with ``127.0.0.1``. They behave differently!
Use ``127.0.0.1`` and do not use ``localhost``.
As an example, if you want to access the MySQL database from within the PHP container, you do the
following:
.. code-block:: bash
:emphasize-lines: 8
# Navigate to Devilbox git directory
host> cd path/to/devilbox
# Enter the PHP container
host> ./shell.sh
# Enter the MySQL console
php> mysql -u root -h 127.0.0.1 -p
mysql>
The very same command applies to access the MySQL database from your host operating system:
.. code-block:: bash
:emphasize-lines: 2
# Enter the MySQL console
host> mysql -u root -h 127.0.0.1 -p
mysql>
So no matter if you use the Devilbox or have another LAMP stack installed locally on your host
operating system, you do not have to change your configuration files if you stick to this tip.
So any of your projects php files that configure MySQL as an example should point the hostname
or IP address of the MySQL server to ``127.0.0.1``:
.. code-block:: php
<?php
// MySQL server connection in your project configuration
mysql_host = '127.0.0.1';
mysql_port = '3306';
mysql_user = 'someusername';
mysql_pass = 'somepassword';
?>
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
Timezone
========
The :ref:`env_timezone` value will affect PHP, web server and MySQL container equally. It does
however not affect any other official Docker container that are used within the Devilbox. This is
an issue that is currently still being worked on.
Feel free to change this to any timezone you require for PHP and MySQL, but keep in mind that
timezone values for databases can be painful, once you want to switch to a different timezone.
A good practice is to always use ``UTC`` on databases and have your front-end application calculate
the correct time for the user. This way you will be more independent of any changes.

239
docs/getting-started/change-container-versions.rst Normal file
View File

@ -0,0 +1,239 @@
*************************
Change container versions
*************************
One of the core concepts of the Devilbox is to easily change between different versions of a
specific service.
**Table of Contents**
.. contents:: :local:
Implications
============
Configuration changes
---------------------
Be aware that every version has its own configuration files in the ``cfg/`` directory.
If you switch to a different version, you might end up with a different custom configuration.
This however only applies, if you have already customized the configuration for your current
service.
.. seealso::
* :ref:`php_ini`
* :ref:`php_fpm_conf`
* :ref:`apache_conf`
* :ref:`nginx_conf`
* :ref:`my_cnf`
Data changes
------------
You also have to be aware that all database services (e.g.: MySQL, PostgreSQL, MongoDB, etc) use
a per version data directory. If you change the database version you might find that you have an
empty database when starting another version.
This is simply a pre-caution to prevent newer versions from upgrading the database files and
accidentally making them incompatible for older versions.
If you want to take your data along, do a backup before switching the version and then re-import
after the switch:
.. seealso::
* :ref:`backup_and_restore_mysql`
* :ref:`backup_and_restore_pgsql`
* :ref:`backup_and_restore_mongo`
Examples
========
Change PHP version
------------------
Stop the Devilbox
^^^^^^^^^^^^^^^^^
Shut down the Devilbox in case it is still running:
.. code-block:: bash
# Navigate to the Devilbox directory
host> cd path/to/devilbox
# Stop all container
host> docker-compose stop
Edit the ``.env`` file
^^^^^^^^^^^^^^^^^^^^^^
Open the ``.env`` file with your favourite editor and navigate to the ``PHP_SERVER`` section.
It will look something like this:
.. code-block:: bash
:caption: .env
:emphasize-lines: 6
#PHP_SERVER=5.3
#PHP_SERVER=5.4
#PHP_SERVER=5.5
#PHP_SERVER=5.6
#PHP_SERVER=7.0
PHP_SERVER=7.1
#PHP_SERVER=7.2
#PHP_SERVER=7.3
As you can see, all available values are already there, but commented. Only one is uncommented.
In this example it is ``7.1``, which is the PHP version that will be started, once the Devilbox
starts.
To change this, simply uncomment your version of choice and save this file. Do not forget to comment
(disable) any other version.
In order to enable PHP 5.5, you would change the ``.env`` file like this:
.. code-block:: bash
:caption: .env
:emphasize-lines: 3
#PHP_SERVER=5.3
#PHP_SERVER=5.4
PHP_SERVER=5.5
#PHP_SERVER=5.6
#PHP_SERVER=7.0
#PHP_SERVER=7.1
#PHP_SERVER=7.2
#PHP_SERVER=7.3
Start the Devilbox
^^^^^^^^^^^^^^^^^^
Now save the file and you can start the Devilbox again.
.. code-block:: bash
# Navigate to the Devilbox directory
host> cd path/to/devilbox
# Stop all container
host> docker-compose up php httpd bind
.. seealso:: :ref:`start_the_devilbox`
Change web server version
-------------------------
Stop the Devilbox
^^^^^^^^^^^^^^^^^
Shut down the Devilbox in case it is still running:
.. code-block:: bash
# Navigate to the Devilbox directory
host> cd path/to/devilbox
# Stop all container
host> docker-compose stop
Edit the ``.env`` file
^^^^^^^^^^^^^^^^^^^^^^
Open the ``.env`` file with your favourite editor and navigate to the ``HTTPD_SERVER`` section.
It will look something like this:
.. code-block:: bash
:caption: .env
:emphasize-lines: 3
#HTTPD_SERVER=apache-2.2
#HTTPD_SERVER=apache-2.4
HTTPD_SERVER=nginx-stable
#HTTPD_SERVER=nginx-mainline
As you can see, all available values are already there, but commented. Only one is uncommented.
In this example it is ``nginx-stable``, which is the web server version that will be started,
once the Devilbox starts.
To change this, simply uncomment your version of choice and save this file. Do not forget to comment
(disable) any other version.
In order to enable Apache 2.2, you would change the ``.env`` file like this:
.. code-block:: bash
:caption: .env
:emphasize-lines: 1
HTTPD_SERVER=apache-2.2
#HTTPD_SERVER=apache-2.4
#HTTPD_SERVER=nginx-stable
#HTTPD_SERVER=nginx-mainline
Start the Devilbox
^^^^^^^^^^^^^^^^^^
Now save the file and you can start the Devilbox again.
.. code-block:: bash
# Navigate to the Devilbox directory
host> cd path/to/devilbox
# Stop all container
host> docker-compose up php httpd bind
.. seealso:: :ref:`start_the_devilbox`
Change whatever version
-----------------------
When you have read how to change the PHP or web server version, it should be fairly simple to
change any service version. It behaves in the exact same way.
The variable names of all available services with changable versions are in the following format:
``<SERVICE>_SERVER``. Just look through the :ref:`env_file`.
.. seealso::
The following variables control service versions:
:ref:`env_php_server`, :ref:`env_httpd_server`,
:ref:`env_mysql_server`, :ref:`env_pgsql_server`, :ref:`env_redis_server`,
:ref:`env_memcd_server`, :ref:`env_mongo_server`
Gotchas
=======
If two versions are uncommented at the same time, always the last one takes precedence.
Consider this ``.env`` file:
.. code-block:: bash
:caption: .env
:emphasize-lines: 3,5
#PHP_SERVER=5.3
#PHP_SERVER=5.4
PHP_SERVER=5.5
#PHP_SERVER=5.6
PHP_SERVER=7.0
#PHP_SERVER=7.1
#PHP_SERVER=7.2
#PHP_SERVER=7.3
Both, PHP 5.5 and PHP 7.0 are uncommented, however, when you start the Devilbox, it will use
PHP 7.0 as this value overwrites any previous ones.
Checklist
=========
1. Stop the Devilbox
2. Uncomment version of choice in ``.env``
3. Start the Devilbox

114
docs/getting-started/create-your-first-project.rst
View File

@ -21,11 +21,14 @@ Create your first project
Step 1: visit Intranet vhost page
=================================
Before starting, have a look at the vhost page at http://localhost/vhosts.php
Before starting, have a look at the vhost page at http://localhost/vhosts.php or
http://127.0.0.1/vhosts.php
.. seealso:: :ref:`howto_find_docker_toolbox_ip_address`
It should look like the screenshot below and will actually already provide the information needed to create a new project.
.. image:: /_static/img/devilbox-vhosts-empty.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-vhosts-empty.rst
Step 2: create a project directory
@ -50,7 +53,7 @@ In your Devilbox git directory, navigate to ``./data/www`` and create a new dire
Visit the vhost page again and see what has changed: http://localhost/vhosts.php
.. image:: /_static/img/devilbox-vhosts-directory.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-vhosts-missing-htdocs.rst
**So what has happened?**
@ -78,16 +81,17 @@ Navigate to your newly created project directory and create a directory named `h
Vist the vhost page again and see what has changed: http://localhost/vhosts.php
.. image:: /_static/img/devilbox-vhosts-dns.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-vhosts-missing-dns.rst
**So what has happened?**
By having created the docroot directory, the web server is now able to serve your files. However it has noticed, that you have no way yet, to actually visit your project url, as no DNS record for it exists yet.
By having created the docroot directory, the web server is now able to serve your files. However
it has noticed, that you have no way yet, to actually visit your project url, as no DNS record for
it exists yet.
The intranet already gives you the exact string that you can simply copy into your ``/etc/hosts`` file on your host operating system to solve this issue.
.. important::
This will only work on **native Docker** for Linux or MacOS. Read up on the next section to also find out how to do that on **Docker Toolbox** and Windows.
The intranet already gives you the exact string that you can simply copy into your ``/etc/hosts``
(or ``C:\Windows\System32\drivers\etc`` for Windows) file on your host operating system to solve
this issue.
.. _getting_started_create_your_first_project_dns_entry:
@ -100,11 +104,8 @@ Step 4: create a DNS entry
DNS entries to your host computer, but is outside the scope of this
*getting started tutorial*.
Add DNS for Linux and MacOS (native Docker)
-------------------------------------------
On Linux and MacOS (when using the native Docker), this step is fairly simple. The intranet provides
you the exact string you need to paste into your ``/etc/hosts`` file on your host operating system.
When using native Docker, the Devilbox intranet will provide you the exact string you need to paste
into your ``/etc/hosts`` (or ``C:\Windows\System32\drivers\etc`` for Windows).
.. code-block:: bash
@ -114,53 +115,15 @@ you the exact string you need to paste into your ``/etc/hosts`` file on your hos
127.0.0.1 project-1.loc
Add DNS for Windows (native Docker)
-----------------------------------
.. seealso::
On Windows (when using the native Docker), you can also copy paste the command provided by the intranet,
however the destination file is different. You have to add this string into: ``C:\Windows\System32\drivers\etc``.
* :ref:`howto_add_project_dns_entry_on_mac`
* :ref:`howto_add_project_dns_entry_on_win`
Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add the following entry
.. code-block:: bash
127.0.0.1 project-1.loc
Add DNS for Docker Toolbox
--------------------------
When using ``Docker Toolbox`` the Devilbox runs inside a virtual machine and therefore the Webserver port (``80``)
is not exposed to your host operating system. So your DNS record must point to the virtual machine instead of your
host system.
1. Find out the IP address the virtual machine is running on
2. Add a DNS entry to your host operating system for this IP address.
For the sake of this example, let's assume the virtual machine is running on ``192.16.0.1``, then the DNS record you will
have to add instead on your host operating system is:
**Docker Toolbox on MacOS**
.. code-block:: bash
host> sudo vi /etc/hosts
192.16.0.1 project-1.loc
**Docker Toolbox on Windows**
Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add the following entry
.. code-block:: bash
192.16.0.1 project-1.loc
Back to intranet
----------------
Vist the vhost page again and see what has changed: http://localhost/vhosts.php
.. image:: /_static/img/devilbox-vhosts-finished.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-vhosts-working.rst
**So what has happened?**
@ -168,13 +131,13 @@ By having created the DNS record, the Devilbox intranet is aware that everything
gives you a link to your new project.
Step 5: Visit your project
Step 5: visit your project
==========================
On the intranet, click on your project link. This will open your project in a new Browser tab or
visit http://project-1.loc
.. image:: /_static/img/devilbox-project-no-files.png
.. include:: ../_includes/figures/devilbox/devilbox-project-missing-index.rst
**So what has happened?**
@ -183,8 +146,8 @@ Everything is setup now, however the webserver is trying to find a ``index.php``
So all is left for you to do is to add your HTML or PHP files.
Step 6: Create a hello world
============================
Step 6: create a hello world file
=================================
Navigate to your docroot directory within your project and create a ``index.php`` file with some output.
@ -207,7 +170,7 @@ Alternatively create an ``index.php`` file in ``data/www/project-1/htdocs`` with
Visit your project url again and see what has changed: http://project-1.loc
.. image:: /_static/img/devilbox-project-hello-world.png
.. include:: ../_includes/figures/devilbox/devilbox-project-hello-world.rst
Checklist
@ -217,3 +180,32 @@ Checklist
2. Docroot directory is created
3. DNS entry is added to the host operating system
4. PHP files are added to your docroot directory
Further examples
================
If you already want to know how to setup specific frameworks on the Devilbox, jump directly to
their articles:
.. seealso::
**Well tested frameworks on the Devilbox**
* :ref:`example_setup_cakephp`
* :ref:`example_setup_codeigniter`
* :ref:`example_setup_drupal`
* :ref:`example_setup_joomla`
* :ref:`example_setup_laravel`
* :ref:`example_setup_phalcon`
* :ref:`example_setup_photon_cms`
* :ref:`example_setup_symfony`
* :ref:`example_setup_wordpress`
* :ref:`example_setup_yii`
* :ref:`example_setup_zend`
.. seealso::
**Generic information for all unlisted frameworks**
* :ref:`example_setup_other_frameworks`

22
docs/getting-started/the-intranet.rst → docs/getting-started/devilbox-intranet.rst
View File

@ -1,9 +1,9 @@
************
The Intranet
************
*****************
Devilbox intranet
*****************
The intranet is your command & control center showing all kinds of information and settings
currently in effect. It also offers third-party projects to do all sorts of database
The Devilbox intranet is your command & control center showing all kinds of information and
settings currently in effect. It also offers third-party projects to do all sorts of database
manipulation.
@ -22,7 +22,7 @@ The start page is there to check if everything works as expected. It shows all d
containers you wanted to start and if they succeeded, as well as their ports, mount points and
special settings applied via ``.env``.
.. image:: /_static/img/devilbox-index.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-index.rst
Virtual hosts
@ -31,7 +31,7 @@ Virtual hosts
The virtual host page displays all available projects and let's you know if their configuration
is correct, such as DNS settings or document root.
.. image:: /_static/img/devilbox-vhosts.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-vhosts.rst
Emails
@ -40,7 +40,7 @@ Emails
The email page displays all emails that would have been sent, but were caught by the integrated
email catch-all functionality.
.. image:: /_static/img/devilbox-emails.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-emails.rst
Databases
@ -51,7 +51,7 @@ what is currently in place, how many databases/schemas and or recors and what si
The following example shows the database page for MySQL:
.. image:: /_static/img/devilbox-database.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-mysql-databases.rst
Info pages
@ -62,11 +62,11 @@ currently applied.
The following example shows you the info page for PHP.
.. image:: /_static/img/devilbox-info-php.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-php-info.rst
The following example shows you the info page for MySQL:
.. image:: /_static/img/devilbox-info-mysql.png
.. include:: ../_includes/figures/devilbox/devilbox-intranet-mysql-info.rst
Third-party tools

17
docs/getting-started/email-catch-all.rst
View File

@ -1,17 +0,0 @@
.. _getting_started_email_catch_all:
***************
Email catch-all
***************
All your projects can send emails to whatever recipient. You do not have to worry that they will
actually being sent. Each PHP container runs a local postfix mailserver that intercepts
all outgoing mails and puts them into a local mailbox by the user ``devilbox``.
In order to view sent emails open up the devilbox intranet http://localhost/mail.php.
There you can also test email sending and verify that they really stay locally.
.. image:: /_static/img/devilbox-email-catch-all.png
In the above image from the intranet you can see that all emails sent to whatever recipient
have been caught by the Devilbox and are available to be read.

6
docs/getting-started/enter-the-php-container.rst
View File

@ -2,7 +2,7 @@
Enter the PHP container
***********************
Another core feature of the Devilbox is, to be totally independent of what you have or have not
Another core feature of the Devilbox, is to be totally independent of what you have or have not
installed on your host operating system.
The Devilbox already ships with many common developer tools which are installed inside each PHP
@ -100,7 +100,7 @@ automatically pushed to Docker hub to ensure versions are outdated at a maximum
The only thing you have to do, is to update the Docker images itself, simply by pulling a new version.
.. seealso:: :ref:`getting_started_update_the_docker_images`
.. seealso:: :ref:`update_the_devilbox_update_the_docker_images`
Advanced
@ -109,7 +109,7 @@ Advanced
This is just a short overview about the possibility to work inside the container.
If you want to dig deeper into this topic there is also a more advanced tutorial available:
.. seealso:: :ref:`tutorial_work_inside_the_php_container`
.. seealso:: :ref:`work_inside_the_php_container`
Checklist

118
docs/getting-started/install-the-devilbox.rst
View File

@ -1,10 +1,13 @@
.. include:: ../_includes/global/links.rst
.. _install_the_devilbox:
********************
Install the Devilbox
********************
.. important::
:ref:`read_first`
Ensure you have read this document to understand how this documentation works.
Ensure you have read and followed the :ref:`prerequisites`
**Table of Contents**
@ -12,108 +15,45 @@ Install the Devilbox
.. contents:: :local:
Supported OS
============
The devilbox runs on all operating systems that provide ``Docker`` and ``Docker Compose``.
+------------+------------+------------+
| |logo_lin| | |logo_win| | |logo_osx| |
+------------+------------+------------+
.. |logo_lin| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/linux.png
.. |logo_osx| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/osx.png
.. |logo_win| image:: https://raw.githubusercontent.com/cytopia/icons/master/64x64/windows.png
Requirements
============
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::
:ref:`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.
.. seealso::
:ref:`install_docker`
Have a look at this page to help you install ``Docker`` for your operating system.
:ref:`install_docker_compose`
Have a look at this page to help you install ``Docker Compose`` for your operating system.
Download the devilbox
Download the Devilbox
=====================
The devilbox does not need to be installed. The only thing that is required is its git directory.
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.
.. code-block:: bash
host> git clone https://github.com/cytopia/devilbox
.. seealso::
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 a
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.
.. code-block:: bash
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.
* :ref:`howto_open_terminal_on_mac`
* :ref:`howto_open_terminal_on_win`
* :ref:`checkout-different-devilbox-release`
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).
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).
.. code-block:: bash
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
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).
.. seealso::
`Docker Compose env file <https://docs.docker.com/compose/env-file/>`_
Official Docker documentation about the ``.env`` file
:ref:`env_file`
All available Devilbox ``.env`` values and their description
* |ext_lnk_docker_cmpose_env_file|
* :ref:`env_file`
Adjust ``.env`` file
====================
Set uid and gid
===============
To get you started, there are only two variables that need to be adjusted:
@ -152,22 +92,18 @@ Open the ``.env`` file with your favorite text editor and adjust those values:
NEW_UID=1001
NEW_GID=1002
.. warning::
Make sure that you use the values provided by ``id -u`` and ``id -g``.
.. seealso::
:ref:`syncronize_container_permissions`
Read up more on the general problem of trying to have syncronized permissions between
the host system and a running Docker container.
* |ext_lnk_uid|
* :ref:`howto_find_uid_and_gid_on_mac`
* :ref:`howto_find_uid_and_gid_on_win`
* :ref:`syncronize_container_permissions`
Checklist
=========
1. ``Docker`` and ``Docker Compose`` are installed at minimum required version
2. Your user is part of the ``docker`` group
3. ``Devilbox`` is cloned
4. ``.env`` file is created
5. User and group id have been set in ``.env`` file
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.

253
docs/getting-started/prerequisites.rst Normal file
View File

@ -0,0 +1,253 @@
.. include:: ../_includes/global/links.rst
.. include:: ../_includes/global/images.rst
.. _prerequisites:
*************
Prerequisites
*************
.. important::
:ref:`read_first`
Ensure you have read this document to understand how this documentation works.
**Table of Contents**
.. contents:: :local:
Supported host OS
=================
The Devilbox runs on all major operating systems which provide ``Docker`` and ``Docker Compose``.
See the matrix below for supported versions:
+----------------+---------------------+---------------------+-------------+
| OS | Version | Type | Recommended |
+================+=====================+=====================+=============+
| |img_logo_lin| | Any | |tbl_docker_lin| | yes |
+----------------+---------------------+---------------------+-------------+
| | | | |
+----------------+---------------------+---------------------+-------------+
| |img_logo_mac| | Any | |tbl_docker_mac| | yes |
| | +---------------------+-------------+
| | | |tbl_docker_tb_mac| | |
+----------------+---------------------+---------------------+-------------+
| | | | |
+----------------+---------------------+---------------------+-------------+
| |img_logo_win| | Windows 7 | |tbl_docker_tb_win| | |
| +---------------------+---------------------+-------------+
| | Windows 10 | |tbl_docker_win| | yes |
| | +---------------------+-------------+
| | | |tbl_docker_tb_win| | |
| +---------------------+---------------------+-------------+
| | Windows Server 2016 | |tbl_docker_win_ee| | yes |
+----------------+---------------------+---------------------+-------------+
.. |tbl_docker_lin| raw:: html
<a target="_blank" href="https://docs.docker.com/install/#server">
Docker <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |tbl_docker_mac| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-mac/install/">
Docker for Mac <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |tbl_docker_tb_mac| raw:: html
<a target="_blank" href="https://docs.docker.com/toolbox/toolbox_install_mac/">
Docker Toolbox <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |tbl_docker_win| raw:: html
<a target="_blank" href="https://docs.docker.com/docker-for-windows/install/">
Docker for Windows <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |tbl_docker_tb_win| raw:: html
<a target="_blank" href="https://docs.docker.com/toolbox/toolbox_install_windows/">
Docker Toolbox <img src="/_static/img/icons/ext-link.svg" />
</a>
.. |tbl_docker_win_ee| raw:: html
<a target="_blank" href="https://www.docker.com/docker-windows-server">
Docker EE <img src="/_static/img/icons/ext-link.svg" />
</a>
Required software
=================
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.
.. seealso::
* |ext_lnk_install_docker|
* |ext_lnk_install_docker_compose|
* :ref:`howto_find_docker_and_docker_compose_version`
Docker installation
===================
Linux
-----
|img_logo_lin|
Docker on Linux 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:
.. code-block:: bash
host> id
uid=1000(cytopia) gid=1000(cytopia) groups=1000(cytopia),999(docker)
.. seealso::
* |ext_lnk_install_docker_centos|
* |ext_lnk_install_docker_debian|
* |ext_lnk_install_docker_fedora|
* |ext_lnk_install_docker_ubuntu|
* |ext_lnk_install_docker_linux_post_steps| (covers ``docker`` group)
Mac
---
|img_logo_mac|
On MacOS Docker is available in two different forms: **Docker for Mac**
and **Docker Toolbox**.
Docker for Mac
^^^^^^^^^^^^^^
Docker for Mac is the native and recommended version to choose when using the
Devilbox.
.. seealso::
Docker for Mac
* |ext_lnk_install_docker_mac|
* |ext_lnk_install_docker_mac_get_started|
Docker Toolbox
^^^^^^^^^^^^^^
If you still want to use Docker Toolbox, ensure you have read its
drawbacks in the below provided links.
.. seealso::
Docker Toolbox
* |ext_lnk_install_docker_toolbox_mac|
* |ext_lnk_install_docker_toolbox_mac_native_vs_toolbox|
* |ext_link_docker_machine|
.. important:: :ref:`howto_docker_toolbox_and_the_devilbox`
Windows
-------
|img_logo_win|
On Windows Docker is available in two different forms: **Docker for Windows**
and **Docker Toolbox**.
Docker for Windows
^^^^^^^^^^^^^^^^^^
Docker for Windows is the native and recommended version to choose when using
the Devilbox. This however is only available since **Windows 10**.
.. seealso::
Docker for Windows
* |ext_lnk_install_docker_win|
* |ext_lnk_install_docker_win_get_started|
Docker Toolbox
^^^^^^^^^^^^^^
If you are on **Windows 7** or still want to use Docker Toolbox, ensure you
have read its drawbacks in the below provided links.
.. seealso::
Docker Toolbox
* |ext_lnk_install_docker_toolbox_win|
* |ext_link_docker_machine|
.. important:: :ref:`howto_docker_toolbox_and_the_devilbox`
Post installation
=================
Read the Docker documentation carefully and follow all **install** and **post-install** steps.
Below are a few stumbling blocks to check that might or might not apply depending on your host
operating system and your Docker version.
.. seealso:: :ref:`troubleshooting`
User settings
-------------
Some versions of Docker require your local user to be in the ``docker`` group
(or ``docker-users`` on Windows).
Shared drives
-------------
Some versions of Docker require you to correctly setup shared drives. Ensure the desired locations
are being made available to Docker and the correct credentials are applied.
Network and firewall
--------------------
On Windows, ensure your firewall allows access to shared drives.
SE Linux
--------
Make sure to read any shortcomings when SE Linux is enabled.
General
-------
It could also help to do a full system restart after the installation has been finished.
Optional previous knowledge
===========================
In order to easily work with the Devilbox you should already be familiar with the following:
* Navigate on the command line
* Docker Compose commands (``up``, ``stop``, ``kill``, ``rm``, ``logs``, ``pull``)
* Docker Compose ``.env`` file
* Know how to use ``git``
.. seealso::
* |ext_lnk_docker_cmpose_cmd_reference|
* |ext_lnk_docker_cmpose_env_file|

94
docs/getting-started/read-log-files.rst
View File

@ -1,94 +0,0 @@
.. _getting_started_read_log_files:
**************
Read log files
**************
The logging behaviour is determined by the value of :ref:`env_docker_logs` inside your ``.env``
file. By default logs are mounted to the host operating system for convenient access.
**Table of Contents**
.. contents:: :local:
Mounted logs
============
By default log files for PHP, the webserver and the MySQL server are mounted to the host system
into your Devilbox git directory under ``./log/``. All logs are separated by service version
in the following format: ``./log/<service>-<version>/``
The log directory structure would look something like this:
.. code-block:: bash
host> cd path/to/devilbox
host> tree log
log/
├── nginx-stable/
│   ├── nginx-stable/
│   ├── defaultlocalhost-access.log
│   ├── defaultlocalhost-error.log
│   ├── <project-name>-access.log # Each project has its own access log
│   ├── <project-name>-error.log # Each project has its own error log
├── mariadb-10.1/
│   ├── error.log
│   ├── query.log
│   ├── slow.log
├── php-fpm-7.1/
│   ├── php-fpm.access
│   ├── php-fpm.error
Use your favorite tools to view log files such as ``tail``, ``less``, ``more``, ``cat`` or others.
.. important::
Currently logs are only mounted for PHP, HTTPD and MYSQL container.
All other services will log to Docker logs.
Docker logs
===========
You can also change the behaviour where logs are streamed by setting :ref:`env_docker_logs`
to ``1`` inside your ``.env`` file. When doing logs are sent to Docker logs.
When using this approach, you need to use the ``docker-compose logs`` command to view your log
files from within the Devilbox git directory.
.. code-block:: bash
:emphasize-lines: 2
host> cd path/to/devilbox
host> docker-compose logs
When you want to continuously watch the log output (such as ``tail -f``), you need to append ``-f``
to the command.
.. code-block:: bash
:emphasize-lines: 2
host> cd path/to/devilbox
host> docker-compose logs -f
When you only want to have logs displayed for a single service, you can also append the service
name (works with or without ``-f`` as well):
.. code-block:: bash
:emphasize-lines: 2
host> cd path/to/devilbox
host> docker-compose logs php -f
.. important::
This currently does not work for the MySQL container, which will always log to file.
Checklist
=========
1. You know how to switch between file and Docker logs
2. You know where log files are mounted
3. You know how to access Docker logs

27
docs/getting-started/start-the-devilbox.rst
View File

@ -9,11 +9,11 @@ hands dirty.
.. note::
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/>`_ commands.
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/>`_ commands.
**Table of Contents**
@ -63,18 +63,19 @@ http://127.0.0.1.
The Intranet start page will also show you all running and failed containers:
.. image:: /_static/img/devilbox-dash-full.png
.. image:: /_static/img/devilbox-dash-selective.png
.. warning::
:ref:`docker_toolbox`
When you are using ``Docker Toolbox`` the Devilbox Web server port will not be available on
your host computer. You have to forward the virtual machines port to your host computer.
Read more about it on this guide.
.. include:: ../_includes/figures/devilbox/devilbox-intranet-dash-all.rst
.. include:: ../_includes/figures/devilbox/devilbox-intranet-dash-selective.rst
.. important::
:ref:`howto_find_docker_toolbox_ip_address`
When you are using ``Docker Toolbox`` the Devilbox web server port will not be available on
your host computer. You first have to find out on which IP address the Docker Toolbox machine
is serving and use this one instead.
Checklist
=========
1. Docker container are started successfully with ``docker-compose up``
2. Intranet is reachable via ``http://localhost`` or ``http://127.0.0.1``
2. Intranet is reachable via ``http://localhost``, ``http://127.0.0.1`` or Docker Toolbox IP address

203
docs/getting-started/update-the-devilbox.rst
View File

@ -1,203 +0,0 @@
.. _getting_started_update_the_devilbox:
*******************
Update the Devilbox
*******************
If you are in the initial install process, you can safely skip this section and come back once
you actually want to update the Devilbox.
**Table of Contents**
.. contents:: :local:
Update git repository
=====================
Stop container
--------------
Before updating your git branch or checking out a different tag or commit, make sure to properly
stop all devilbox containers:
.. code-block:: bash
# Stop containers
host> cd path/to/devilbox
host> docker-compose stop
# Ensure containers are stopped
host> docker-compose ps
Case 1: Update master branch
----------------------------
If you simply want to update the master branch, do a ``git pull origin master``:
.. code-block:: bash
# Update master branch
host> cd path/to/devilbox
host> git pull origin master
Case 2: Checkout release tag
----------------------------
If you want to checkout a specific release tag (such as ``0.12.1``), do a ``git checkout 0.12.1``:
.. code-block:: bash
# Checkout release
host> cd path/to/devilbox
host> git checkout 0.12.1
Keep ``.env`` file in sync
--------------------------
.. 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.
You can also compare your current ``.env`` file with the provided ``env-example`` file by using
your favorite diff editor:
.. code-block:: bash
host> vimdiff .env env-example
.. code-block:: bash
host> diff .env env-example
.. code-block:: bash
host> meld .env env-example
Recreate container
------------------
Whenever the path of a volume changes (either due to upstream changes in git or due to you changing
it manually in the ``.env`` file) you need to remove the stopped container and have them fully
recreated during the next start.
.. code-block:: bash
# Remove anonymous volumes
host> cd path/to/devilbox
host> docker-compose rm
.. seealso::
:ref:`remove_stopped_container`
.. _getting_started_update_the_docker_images:
Update Docker images
====================
Updating the git branch shouldn't be needed to often, most changes are actually shipped via newer
``Docker images``, so you should frequently update those.
This is usually achieved by issueing a ``docker pull`` command with the correct image name and image
version or ``docker-compose pull`` for all currently selected images in ``.env`` file.
For your convenience there is a shell script in the Devilbox git directory: ``update-docker.sh``
which will update all available Docker images at once for every version.
.. note::
The Devilbox own Docker images (Apache, Nginx, PHP and MySQL) are even built every night to ensure
latest security patches and tool versions are applied.
Update one Docker image
-----------------------
Updating or pulling a single Docker image is accomplished by ``docker pull <image>:<tag>``.
This is not very handy as it is quite troublesome to do it separately per Docker image.
You first need to find out the image name and then also the currently used image tag.
.. code-block:: bash
host> grep 'image:' docker-compose.yml
image: cytopia/bind:0.11
image: devilbox/php-fpm:${PHP_SERVER:-7.0}-work
image: devilbox/${HTTPD_SERVER:-nginx-stable}:0.13
image: cytopia/${MYSQL_SERVER:-mariadb-10.1}:latest
image: postgres:${PGSQL_SERVER:-9.6}
image: redis:${REDIS_SERVER:-3.2}
image: memcached:${MEMCD_SERVER:-latest}
image: mongo:${MONGO_SERVER:-latest}
After having found the possible candidates, you will still have to find the corresponding value
inside the ``..env`` file. Let's do it for the PHP image:
.. code-block:: bash
host> grep '^PHP_SERVER' .env
PHP_SERVER=5.6
So now you can substitute the ``${PHP_SERVER}`` variable from the first command with ``5.6`` and
finally pull a newer version:
.. code-block:: bash
host> docker pull devilbox/php-fpm:5.6-work
Not very efficient.
Update all currently set Docker images
--------------------------------------
This approach is using ``docker-compose pull`` to update all images, but only for the versions
that are actually set in ``.env``.
.. code-block:: bash
host> docker-compose pull
Pulling bind (cytopia/bind:0.11)...
Pulling php (devilbox/php-fpm:5.6-work)...
Pulling httpd (devilbox/apache-2.2:0.13)...
Pulling mysql (cytopia/mysql-5.7:latest)...
Pulling pgsql (postgres:9.6)...
Pulling redis (redis:4.0)...
Pulling memcd (memcached:1.5.2)...
Pulling mongo (mongo:3.0)...
This is most likely the variant you want.
Update all available Docker images for all versions
---------------------------------------------------
In case you also want to pull/update every single of every available Devilbox image, you can
use the provided shell script, which has all versions hardcoded and pulls them for you:
.. code-block:: bash
host> ./update-docker.sh
Checklist git repository
========================
1. Ensure containers are stopped and removed/recreated (``docker-compose stop && docker-compose rm``)
2. Ensure desired branch, tag or commit is checked out or latest changes are pulled
3. Ensure ``.env`` file is in sync with ``env-example`` file
Checklist Docker images
=======================
1. Ensure ``docker-compose pull`` or ``./update-docker.sh`` is executed