ExternalVendorCode/devilbox
1
0
Fork 0
mirror of https://github.com/cytopia/devilbox.git synced 2025-04-12 21:33:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Extend env file documentation

Browse Source
This commit is contained in:
cytopia 2018-03-16 09:25:51 +01:00
parent 9b41a2468c
commit c587e97eba
No known key found for this signature in database
GPG Key ID: 6D56EDB8695128A2
7 changed files with 598 additions and 143 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

431
docs/configuration-files/env-file.rst
View File

@ -11,13 +11,13 @@ variables parsed to docker-compose.yml.
what is the `.env <https://docs.docker.com/compose/env-file/>`_ file?
**Content**
**Table of Contents**
.. contents:: :local:
General settings
================
Core settings
=============
DEBUG_COMPOSE_ENTRYPOINT
------------------------
@ -39,6 +39,9 @@ DEVILBOX_PATH
This specifies a relative or absolute path to the Devilbox git directory and will be used as a
prefix for all Docker mount paths.
* Relative path: relative to the devilbox git directory (Must start with ``.``)
* Absolute path: Full path (Must start with ``/``)
The only reason you would ever want change this variable is when you are on MacOS and relocate
your project files onto an NFS volume due to performance issues.
@ -82,15 +85,52 @@ colon (``:``).
| | listen on all host computer interfaces / IP addresses |
+------------------+-------------------------------------------------------------------------------+
.. note::
When using ``Docker Toolbox``, you must leave this variable empty, in order to have the exposed
ports available on the external interface of the virtual machine.
TLD_SUFFIX
----------
This variable controls all of your projects domain suffix.
+----------------+------------------+---------------+
| Name | Allowed values | Default value |
+================+==================+===============+
| ``TLD_SUFFIX`` | alpha-num string | ``loc`` |
+----------------+------------------+---------------+
Your project domains are built together out of the project directory name and the ``TLD_SUFFIX``.
The formula is like this: ``http://<project-dir>.<TLD_SUFFIX>``.
You can even use official tld's and have your nameserver point to an internal LAN id, to make
this project visible to everyone in your corporate LAN.
**How does it look?**
+-------------+----------------+---------------------------+
| Project dir | ``TLD_SUFFIX`` | Project URL |
+=============+================+===========================+
| my-test | ``loc`` | ``http://my-test.loc`` |
+-------------+----------------+---------------------------+
| example | ``loc`` | ``http://example.loc`` |
+-------------+----------------+---------------------------+
| www.test | ``loc`` | ``http://www.test.loc`` |
+-------------+----------------+---------------------------+
| my-test | ``local`` | ``http://my-test.local`` |
+-------------+----------------+---------------------------+
| example | ``local`` | ``http://example.local`` |
+-------------+----------------+---------------------------+
| www.test | ``local`` | ``http://www.test.local`` |
+-------------+----------------+---------------------------+
| my-test | ``net`` | ``http://my-test.net`` |
+-------------+----------------+---------------------------+
| example | ``com`` | ``http://example.com`` |
+-------------+----------------+---------------------------+
| www.test | ``org`` | ``http://www.test.org`` |
+-------------+----------------+---------------------------+
.. note::
When using ``Docker Toolbox``, you must leave this variable empty, in order to have the exposed
ports available on the external interface of the virtual machine.
.. _env_new_uid:
@ -173,3 +213,382 @@ Have a look at Wikipedia to get a list of valid timezones: https://en.wikipedia.
.. note::
It is always a good practice not to assume a specific timezone anyway and store all values
in UTC (such as time types in MySQL).
Intranet settings
=================
DNS_CHECK_TIMEOUT
-----------------
The Devilbox intranet validates if every project has a corresponding DNS record (either an official
DNS record, one that came from its own Auto-DNS or an ``/etc/hosts`` entry). By doing so it queries
the DNS record based on ``<project-dir>.<TLD_SUFFIX>``. In case it does not exist, the query itself
might take a while and the intranet page will be unresponsive during that time. In order to avoid
long waiting times, you can set the DNS query time-out in seconds after which the query should stop
and report as unsuccessful. The default is ``1`` second, wich should be fairly sane for all use-cases.
+-----------------------+----------------+-------------------+
| Name | Allowed values | Default value |
+=======================+================+===================+
| ``DNS_CHECK_TIMEOUT`` | integers | ``1`` |
+-----------------------+----------------+-------------------+
DEVILBOX_UI_PROTECT
-------------------
By setting this variable to ``1``, the Devilbox intranet will be password protected.
This might be useful, if you share your running Devilbox instance accross a LAN, but do not want
everybody to have access to the intranet itself, just to the projects you actually provide.
+-------------------------+----------------+-------------------+
| Name | Allowed values | Default value |
+=========================+================+===================+
| ``DEVILBOX_UI_PROTECT`` | ``0`` or ``1`` | ``0`` |
+-------------------------+----------------+-------------------+
.. note::
Also pay attention to the next env var, which will control the password for the login:
``DEVILBOX_UI_PASSWORD``.
DEVILBOX_UI_PASSWORD
--------------------
When the devilbox intranet is password-protected via ``DEVILBOX_UI_PROTECT``, this is the actual
password by which it will be protected.
+--------------------------+----------------+-------------------+
| Name | Allowed values | Default value |
+==========================+================+===================+
| ``DEVILBOX_UI_PASSWORD`` | any string | ``password`` |
+--------------------------+----------------+-------------------+
DEVILBOX_UI_DISABLE
-------------------
In case you want to completely disable the Devilbox intranet, such as when running it on production,
you need to set this variable to ``1``.
By disabling the intranet, the webserver will simply remove the default virtual host and redirect
all IP-based requests to the first available virtual host, which will be you first project when
ordering their names alphabetically.
+-------------------------+----------------+-------------------+
| Name | Allowed values | Default value |
+=========================+================+===================+
| ``DEVILBOX_UI_DISABLE`` | ``0`` or ``1`` | ``0`` |
+-------------------------+----------------+-------------------+
Docker image versions
=====================
The following settings reflect one of the main goals of the Devilbox: being able to run any
combination of all container versions.
.. note::
Any change for those settings requires a restart of the devilbox.
PHP_SERVER
----------
This variable choses your desired PHP-FPM version to be started.
+-------------------------+--------------------------------------------------------------------------------------------------------------------------+-----------------+
| Name | Allowed values | Default value |
+=========================+==========================================================================================================================+=================+
| ``PHP_SERVER`` | ``php-fpm-5.4`` |br| ``php-fpm-5.5`` |br| ``php-fpm-5.6`` |br| ``php-fpm-7.0`` |br| ``php-fpm-7.1`` |br| ``php-fpm-7.2`` | ``php-fpm-7.1`` |
+-------------------------+--------------------------------------------------------------------------------------------------------------------------+-----------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 7
host> grep PHP_SERVER .env
#PHP_SERVER=php-fpm-5.4
#PHP_SERVER=php-fpm-5.5
#PHP_SERVER=php-fpm-5.6
#PHP_SERVER=php-fpm-7.0
PHP_SERVER=php-fpm-7.1
#PHP_SERVER=php-fpm-7.2
#PHP_SERVER=php-fpm-7.3
#PHP_SERVER=hhvm-latest
HTTPD_SERVER
------------
This variable choses your desired web server version to be started.
+-------------------------+----------------------------------------------------------------------------------+------------------+
| Name | Allowed values | Default value |
+=========================+==================================================================================+==================+
| ``HTTPD_SERVER`` | ``apache-2.2`` |br| ``apache-2.4`` |br| ``nginx-stable`` |br| ``nginx-mainline`` | ``nginx-stable`` |
+-------------------------+----------------------------------------------------------------------------------+------------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 5
host> grep HTTPD_SERVER .env
#HTTPD_SERVER=apache-2.2
#HTTPD_SERVER=apache-2.4
HTTPD_SERVER=nginx-stable
#HTTPD_SERVER=nginx-mainline
MYSQL_SERVER
------------
This variable choses your desired MySQL server version to be started.
+-------------------------+------------------------------------------------------------------------------------------------+------------------+
| Name | Allowed values | Default value |
+=========================+================================================================================================+==================+
| ``MYSQL_SERVER`` | ``mysql-5.5`` |br| ``mysql-5.6`` |br| ``mariadb-10.2`` |br| ``percona-5.7`` |br| and many more | ``mariadb-10.1`` |
+-------------------------+------------------------------------------------------------------------------------------------+------------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 9
host> grep MYSQL_SERVER .env
#MYSQL_SERVER=mysql-5.5
#MYSQL_SERVER=mysql-5.6
#MYSQL_SERVER=mysql-5.7
#MYSQL_SERVER=mysql-8.0
#MYSQL_SERVER=mariadb-5.5
#MYSQL_SERVER=mariadb-10.0
MYSQL_SERVER=mariadb-10.1
#MYSQL_SERVER=mariadb-10.2
#MYSQL_SERVER=mariadb-10.3
#MYSQL_SERVER=percona-5.5
#MYSQL_SERVER=percona-5.6
#MYSQL_SERVER=percona-5.7
PGSQL_SERVER
------------
This variable choses your desired PostgreSQL server version to be started.
+-------------------------+-------------------------------------------------------------------+------------------+
| Name | Allowed values | Default value |
+=========================+===================================================================+==================+
| ``PGSQL_SERVER`` | ``9.1`` |br| ``9.2`` |br| ``9.3`` |br| ``9.4`` |br| and many more | ``9.6`` |
+-------------------------+-------------------------------------------------------------------+------------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 8
host> grep PGSQL_SERVER .env
#PGSQL_SERVER=9.1
#PGSQL_SERVER=9.2
#PGSQL_SERVER=9.3
#PGSQL_SERVER=9.4
#PGSQL_SERVER=9.5
PGSQL_SERVER=9.6
#PGSQL_SERVER=10.0
.. note::
This is the official PostgreSQL server which might already have other tags available,
check their official website for even more versions.
https://hub.docker.com/_/postgres/
REDIS_SERVER
------------
This variable choses your desired Redis server version to be started.
+-------------------------+-------------------------------------------------------------------+------------------+
| Name | Allowed values | Default value |
+=========================+===================================================================+==================+
| ``REDIS_SERVER`` | ``2.8`` |br| ``3.0`` |br| ``3.2`` |br| ``4.0`` |br| and many more | ``4.0`` |
+-------------------------+-------------------------------------------------------------------+------------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 6
host> grep REDIS_SERVER .env
#REDIS_SERVER=2.8
#REDIS_SERVER=3.0
#REDIS_SERVER=3.2
REDIS_SERVER=4.0
.. note::
This is the official Redis server which might already have other tags available,
check their official website for even more versions.
https://hub.docker.com/_/redis/
MEMCD_SERVER
------------
This variable choses your desired Memcached server version to be started.
+-------------------------+-------------------------------------------------------------------------------+------------------+
| Name | Allowed values | Default value |
+=========================+===============================================================================+==================+
| ``MEMCD_SERVER`` | ``1.4.21`` |br| ``1.4.22`` |br| ``1.4.23`` |br| ``1.4.24`` |br| and many more | ``1.5.2`` |
+-------------------------+-------------------------------------------------------------------------------+------------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 24
host> grep MEMCD_SERVER .env
#MEMCD_SERVER=1.4.21
#MEMCD_SERVER=1.4.22
#MEMCD_SERVER=1.4.23
#MEMCD_SERVER=1.4.24
#MEMCD_SERVER=1.4.25
#MEMCD_SERVER=1.4.26
#MEMCD_SERVER=1.4.27
#MEMCD_SERVER=1.4.28
#MEMCD_SERVER=1.4.29
#MEMCD_SERVER=1.4.30
#MEMCD_SERVER=1.4.31
#MEMCD_SERVER=1.4.32
#MEMCD_SERVER=1.4.33
#MEMCD_SERVER=1.4.34
#MEMCD_SERVER=1.4.35
#MEMCD_SERVER=1.4.36
#MEMCD_SERVER=1.4.37
#MEMCD_SERVER=1.4.38
#MEMCD_SERVER=1.4.39
#MEMCD_SERVER=1.5.0
#MEMCD_SERVER=1.5.1
MEMCD_SERVER=1.5.2
#MEMCD_SERVER=latest
.. note::
This is the official Memcached server which might already have other tags available,
check their official website for even more versions.
https://hub.docker.com/_/memcached/
MONGO_SERVER
------------
This variable choses your desired MongoDB server version to be started.
+-------------------------+-------------------------------------------------------------------+------------------+
| Name | Allowed values | Default value |
+=========================+===================================================================+==================+
| ``MONGO_SERVER`` | ``2.8`` |br| ``3.0`` |br| ``3.2`` |br| ``3.4`` |br| and many more | ``3.4`` |
+-------------------------+-------------------------------------------------------------------+------------------+
All values are already available in the ``.env`` file and just need to be commented or uncommented. If multiple values are uncommented, the last uncommented variable one takes precedences:
.. code-block:: bash
:caption: .env
:name: .env
:emphasize-lines: 6
host> grep MONGO_SERVER .env
#MONGO_SERVER=2.8
#MONGO_SERVER=3.0
#MONGO_SERVER=3.2
MONGO_SERVER=3.4
#MONGO_SERVER=3.5
.. note::
This is the official MongoDB server which might already have other tags available,
check their official website for even more versions.
https://hub.docker.com/_/mongo/
Docker host mounts
==================
The Docker host mounts are directory paths on your host operating system that will be mounted into
the running Docker container. This makes data persistent accross restarts and let them be available
on both sides: Your host operating system as well as inside the container.
This also gives you the choice to edit data on your host operating system, such as with your
favourite IDE/editor and also inside the container, by using the bundled tools, such as
downloading libraries with ``composer`` and others.
Being able to do that on both sides, removes the need to install any development tools (except your
IDE/editor) on your host and have everything fully encapsulated into the containers itself.
HOST_PATH_HTTPD_DATADIR
-----------------------
This is an absolute or relative path (relative to Devilbox git directory) to your data directory.
.. seealso::
:ref:`getting_started_directory_overview_datadir`
By default, all of your websites/projects will be stored in that directory. If however you want
to separate your data from the Devilbox git directory, do change the path to a place where you
want to store all of your projects on your host computer.
* Relative path: relative to the devilbox git directory (Must start with ``.``)
* Absolute path: Full path (Must start with ``/``)
+------------------------------+----------------+----------------+
| Name | Allowed values | Default value |
+==============================+================+================+
| ``HOST_PATH_HTTPD_DATADIR`` | valid path | ``./data/www`` |
+------------------------------+----------------+----------------+
Example
^^^^^^^
If you want to move all your projects to ``/home/myuser/workspace/web/`` for example, just set it
like this:
.. code-block:: bash
:caption: .env
:name: .env
HOST_PATH_HTTPD_DATADIR=/home/myuser/workspace/web
Mapping
^^^^^^^
No matter what path you assign, inside the PHP and the web server container your data dir will
always be ``/shared/httpd/``.
.. |br| raw:: html
<br />

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

@ -1,3 +1,5 @@
.. _getting_started_create_your_first_project:
*************************
Create your first project
*************************
@ -7,132 +9,14 @@ Create your first project
This section not only applies for one project, it applied for as many projects as you need.
**There is no limit in the number of projects.**
.. _prerequisites:
Prerequisites
=============
**Table of Contents**
.. important::
The prerequisites section only provides you some theoretical, but useful insights about how
it all works together. You should at least read it once to be able to debug any problems you
might encounter.
.. contents:: :local:
If you have read it already, jump directly to :ref:`project_creation_workflow`
Data directory
--------------
By default all your projects must be created in the ``./data/www/`` directory which is inside in
your Devilbox git directory. This can be changed as well, but is outside the scope of this
*getting started tutorial*.
You can verifiy that the path is actually ``./data/www/`` by checking your ``.env`` file:
.. code-block:: bash
host> grep HTTPD_DATADIR .env
HOST_PATH_HTTPD_DATADIR=./data/www
Project directory
-----------------
The project directory is a directory directly within the data directory.
**This represents one project.**
By creating this directory, the web server will create a new virtual host for you. This
happens fully automated and there is nothing else required to do except just to create a directory.
The name of this directory will also be used to build up the final project url together with the
domain suffix: ``http://<project directory>.<domain suffix>``
Create as many project directories as you require.
Docroot directory
-----------------
The docroot directory is a directory within each project directory from which the webserver will serve the files.
By default this directory must be named ``htdocs``. This can be changed as well, but is outside
the scope of this *getting started tutorial*.
You can verifiy that the docroot directory is actually ``htdocs`` by checking your ``.env`` file:
.. code-block:: bash
host> grep DOCROOT_DIR .env
HTTPD_DOCROOT_DIR=htdocs
Domain suffix
-------------
The default domain suffix (``TLD_SUFFIX`` variable in ``.env`` file) is ``loc``. That means that
all your projects will be available under the following address: ``http://<project-directory>.loc``.
This can be changed as well, but is outside the scope of this *getting started tutorial*.
You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` file:
.. code-block:: bash
host> grep ^TLD_SUFFIX .env
TLD_SUFFIX=loc
Making sense of it
------------------
Ok, let's sum it up and make sense of the previously provided information. To better illustrate
the behaviour we are going to use ``project-1`` as our project directory name.
+---------------+---------------------------------+-------------------------------------------------------------+
| Item | Example | Description |
+===============+=================================+=============================================================+
| data dir | ``./data/www`` | Where all of your projects reside. |
+---------------+---------------------------------+-------------------------------------------------------------+
| project dir | ``./data/www/project-1`` | A single project. It's name will be used to create the url. |
+---------------+---------------------------------+-------------------------------------------------------------+
| docroot dir | ``./data/www/project-1/htdocs`` | Where the webserver looks for files within your project. |
+---------------+---------------------------------+-------------------------------------------------------------+
| domain suffix | ``loc`` | Suffix to build up your project url. |
+---------------+---------------------------------+-------------------------------------------------------------+
| project url | ``http://project-1.loc`` | Final resulting project url. |
+---------------+---------------------------------+-------------------------------------------------------------+
**data dir**
This directory is mounted into the ``httpd`` and ``php`` container, so that both know where all projects can be found. This is also the place where you create ``project directories`` for each of your projects.
**project dir**
Is your project and used to generate the virtual host together with the domain suffix.
**docroot dir**
A directory inside your ``project dir`` from where the webserver will actually serve your files.
**domain suffix**
Used as part of the project url.
.. note::
The projcet directory will be discussed in more detail in :ref:`project_creation_workflow` below.
.. _project_creation_workflow:
Project creation workflow
=========================
Step 1: visit Intranet vhost page
---------------------------------
=================================
Before starting, have a look at the vhost page at http://localhost/vhosts.php
@ -142,7 +26,7 @@ It should look like the screenshot below and will actually already provide the i
Step 2: create a project directory
----------------------------------
==================================
In your Devilbox git directory, navigate to ``./data/www`` and create a new directory.
@ -169,11 +53,12 @@ Vist the vhost page again and see what has changed: http://localhost/vhosts.php
By having created a project directory, the web server container has created a new virtual host. However it has noticed, that the actual document root directory does not yet exist and therefore it cannot serve any files yet.
Step 3: create a docroot directory
----------------------------------
==================================
.. note::
As desribed in :ref:`prerequisites` the docroot directory name must be ``htdocs`` for now.
As desribed in :ref:`getting_started_directory_overview_docroot` the docroot directory name must be ``htdocs`` for now.
Navigate to your newly created project directory and create a directory named `htdocs` inside it.
@ -201,8 +86,9 @@ The intranet already gives you the exact string that you can simply copy into yo
.. 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.
Step 4: create a DNS entry
--------------------------
==========================
.. note::
This step can also be automated via the bundled DNS server to automatically provide catch-all
@ -210,7 +96,7 @@ Step 4: create a DNS entry
*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.
@ -224,7 +110,7 @@ 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)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------------------------
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``.
@ -236,7 +122,7 @@ Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add th
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
@ -264,9 +150,8 @@ Open ``C:\Windows\System32\drivers\etc`` with admistrative privileges and add th
192.16.0.1 project-1.loc
Back to intranet
^^^^^^^^^^^^^^^^
----------------
Vist the vhost page again and see what has changed: http://localhost/vhosts.php
@ -277,8 +162,9 @@ Vist the vhost page again and see what has changed: http://localhost/vhosts.php
By having created the DNS record, the Devilbox intranet is aware that everything is setup now and
gives you a link to your new 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
@ -291,8 +177,9 @@ 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
----------------------------
============================
Navigate to your docroot directory within your project and create a ``index.php`` file with some output.
@ -321,8 +208,7 @@ Vist your project url again and see what has changed: http://project-1.loc
Checklist
=========
1. :ref:`prerequisites` are read and understood
2. Project directory is created
3. Docroot directory is created
4. DNS entry is added to the host operating system
5. PHP files are added to your docroot directory
1. Project directory is created
2. Docroot directory is created
3. DNS entry is added to the host operating system
4. PHP files are added to your docroot directory

133
docs/getting-started/directory-overview.rst Normal file
View File

@ -0,0 +1,133 @@
.. _getting_started_directory_overview:
******************
Directory overview
******************
.. important::
The directory overview only provides you some theoretical, but useful insights about how
it all works together. You should at least read it once to be able to debug any problems you
might encounter.
If you have read it already, jump directly to :ref:`getting_started_create_your_first_project`
**Table of Contents**
.. contents:: :local:
.. _getting_started_directory_overview_datadir:
Data directory
==============
By default all your projects must be created in the ``./data/www/`` directory which is inside in
your Devilbox git directory. This can be changed as well, but is outside the scope of this
*getting started tutorial*.
You can verifiy that the path is actually ``./data/www/`` by checking your ``.env`` file:
.. code-block:: bash
host> grep HTTPD_DATADIR .env
HOST_PATH_HTTPD_DATADIR=./data/www
Project directory
=================
The project directory is a directory directly within the data directory.
**This represents one project.**
By creating this directory, the web server will create a new virtual host for you. This
happens fully automated and there is nothing else required to do except just to create a directory.
The name of this directory will also be used to build up the final project url together with the
domain suffix: ``http://<project directory>.<domain suffix>``
Create as many project directories as you require.
.. _getting_started_directory_overview_docroot:
Docroot directory
=================
The docroot directory is a directory within each project directory from which the webserver will serve the files.
By default this directory must be named ``htdocs``. This can be changed as well, but is outside
the scope of this *getting started tutorial*.
You can verifiy that the docroot directory is actually ``htdocs`` by checking your ``.env`` file:
.. code-block:: bash
host> grep DOCROOT_DIR .env
HTTPD_DOCROOT_DIR=htdocs
Domain suffix
=============
The default domain suffix (``TLD_SUFFIX`` variable in ``.env`` file) is ``loc``. That means that
all your projects will be available under the following address: ``http://<project-directory>.loc``.
This can be changed as well, but is outside the scope of this *getting started tutorial*.
You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` file:
.. code-block:: bash
host> grep ^TLD_SUFFIX .env
TLD_SUFFIX=loc
Making sense of it
==================
Ok, let's sum it up and make sense of the previously provided information. To better illustrate
the behaviour we are going to use ``project-1`` as our project directory name.
+---------------+---------------------------------+-------------------------------------------------------------+
| Item | Example | Description |
+===============+=================================+=============================================================+
| data dir | ``./data/www`` | Where all of your projects reside. |
+---------------+---------------------------------+-------------------------------------------------------------+
| project dir | ``./data/www/project-1`` | A single project. It's name will be used to create the url. |
+---------------+---------------------------------+-------------------------------------------------------------+
| docroot dir | ``./data/www/project-1/htdocs`` | Where the webserver looks for files within your project. |
+---------------+---------------------------------+-------------------------------------------------------------+
| domain suffix | ``loc`` | Suffix to build up your project url. |
+---------------+---------------------------------+-------------------------------------------------------------+
| project url | ``http://project-1.loc`` | Final resulting project url. |
+---------------+---------------------------------+-------------------------------------------------------------+
**data dir**
This directory is mounted into the ``httpd`` and ``php`` container, so that both know where all projects can be found. This is also the place where you create ``project directories`` for each of your projects.
**project dir**
Is your project and used to generate the virtual host together with the domain suffix.
**docroot dir**
A directory inside your ``project dir`` from where the webserver will actually serve your files.
**domain suffix**
Used as part of the project url.
Checklist
=========
1. You know what the data directory is
2. You know what the project directory is
3. You know what the docroot directory is
4. You know what the domain suffix is
5. You know how domains are constructed

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

@ -7,6 +7,11 @@ Install the Devilbox
Ensure you have read this document to understand how this documentation works.
**Table of Contents**
.. contents:: :local:
Supported OS
============

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

@ -16,6 +16,11 @@ hands dirty.
`stop <https://docs.docker.com/compose/reference/stop/>`_ commands.
**Table of Contents**
.. contents:: :local:
Start all container
===================

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

@ -5,6 +5,12 @@ 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
=====================

1
docs/index.rst
View File

@ -23,6 +23,7 @@ devilbox documentation
getting-started/install-the-devilbox
getting-started/update-the-devilbox
getting-started/start-the-devilbox
getting-started/directory-overview
getting-started/create-your-first-project