mirror of
https://github.com/cytopia/devilbox.git
synced 2025-02-20 17:33:05 +00:00
Info about .env file
This commit is contained in:
cytopia
parent
dc641b9298
commit
9b41a2468c
175
docs/configuration-files/env-file.rst
Normal file
175
docs/configuration-files/env-file.rst
Normal file
@ -0,0 +1,175 @@
|
||||
.. _env_file:
|
||||
|
||||
*********
|
||||
.env file
|
||||
*********
|
||||
|
||||
All docker-compose configuration is done inside the ``.env`` file which simply defines key-value
|
||||
variables parsed to docker-compose.yml.
|
||||
|
||||
.. note::
|
||||
what is the `.env <https://docs.docker.com/compose/env-file/>`_ file?
|
||||
|
||||
|
||||
**Content**
|
||||
|
||||
.. contents:: :local:
|
||||
|
||||
|
||||
General settings
|
||||
================
|
||||
|
||||
DEBUG_COMPOSE_ENTRYPOINT
|
||||
------------------------
|
||||
|
||||
This variable controls the docker-compose log verbosity during service startup.
|
||||
When set to ``1`` verbose output as well as executed commands are shown.
|
||||
When set to ``0`` only warnings and errors are shown.
|
||||
|
||||
+------------------------------+----------------+---------------+
|
||||
| Name | Allowed values | Default value |
|
||||
+==============================+================+===============+
|
||||
| ``DEBUG_COMPOSE_ENTRYPOINT`` | ``0`` or ``1`` | ``1`` |
|
||||
+------------------------------+----------------+---------------+
|
||||
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
.. warning::
|
||||
Whenever you change this value you have to stop the Devilbox and re-create your volumes via
|
||||
``docker-compose rm -f``.
|
||||
|
||||
+-------------------+----------------+---------------+
|
||||
| Name | Allowed values | Default value |
|
||||
+===================+================+===============+
|
||||
| ``DEVILBOX_PATH`` | valid path | ``.`` |
|
||||
+-------------------+----------------+---------------+
|
||||
|
||||
|
||||
LOCAL_LISTEN_ADDR
|
||||
-----------------
|
||||
|
||||
This variable specifies you host computers listening IP address for exposed container ports.
|
||||
If you leave this variable empty, all exposed ports will be bound to all network interfaces on
|
||||
your host operating system, which is also the default behaviour.
|
||||
If you only want the exposed container ports to be bound to a specific IP address (such as
|
||||
``127.0.0.1``), you can add this IP address here, but note, in this case you must add a trailing
|
||||
colon (``:``).
|
||||
|
||||
|
||||
+-----------------------+----------------+---------------+
|
||||
| Name | Allowed values | Default value |
|
||||
+=======================+================+===============+
|
||||
| ``LOCAL_LISTEN_ADDR`` | IP address | empty |
|
||||
+-----------------------+----------------+---------------+
|
||||
|
||||
**Examples:**
|
||||
|
||||
+------------------+-------------------------------------------------------------------------------+
|
||||
| Value | Meaning |
|
||||
+==================+===============================================================================+
|
||||
| ``127.0.0.1:`` | only expose ports on your host os on ``127.0.0.1``. Note the trailing ``:`` |
|
||||
+------------------+-------------------------------------------------------------------------------+
|
||||
| ``192.168.0.1:`` | only expose ports on your host os on ``192.168.0.1``. Note the trailing ``:`` |
|
||||
+------------------+-------------------------------------------------------------------------------+
|
||||
| | listen on all host computer interfaces / IP addresses |
|
||||
+------------------+-------------------------------------------------------------------------------+
|
||||
|
||||
|
||||
TLD_SUFFIX
|
||||
----------
|
||||
|
||||
|
||||
|
||||
.. 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:
|
||||
|
||||
NEW_UID
|
||||
-------
|
||||
|
||||
This setting controls one of the core concepts of the Devilbox. It overcomes the problem of
|
||||
syncronizing file and directory permissions between the Docker container and your host operating
|
||||
system.
|
||||
|
||||
You should set this value to the user id of your host operating systems user you actually work with.
|
||||
How do you find out your user id?
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
host> id -u
|
||||
1000
|
||||
|
||||
In most cases (on Linux and MacOS), this will be ``1000`` if you are the first and only user on
|
||||
your system, however it could also be a different value.
|
||||
|
||||
+-----------------------+----------------+---------------+
|
||||
| Name | Allowed values | Default value |
|
||||
+=======================+================+===============+
|
||||
| ``NEW_UID`` | valid uid | ``1000`` |
|
||||
+-----------------------+----------------+---------------+
|
||||
|
||||
The Devilbox own containers will then pick up this value during startup and change their internal
|
||||
user id to the one specified. Services like PHP-FPM, Apache and Nginx will then do read and write
|
||||
operation of files with this uid, so all files mounted will have permissions as your local user
|
||||
and you do not have to fix permissions afterwards.
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
NEW_GID
|
||||
-------
|
||||
|
||||
This is the equivalent to user id for groups and addresses the same concept. See :ref:`env_new_uid`.
|
||||
|
||||
How do you find out your group id?
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
host> id -g
|
||||
1000
|
||||
|
||||
In most cases (on Linux and MacOS), this will be ``1000`` if you are the first and only user on
|
||||
your system, however it could also be a different value.
|
||||
|
||||
+-----------------------+----------------+---------------+
|
||||
| Name | Allowed values | Default value |
|
||||
+=======================+================+===============+
|
||||
| ``NEW_GID`` | valid gid | ``1000`` |
|
||||
+-----------------------+----------------+---------------+
|
||||
|
||||
.. 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.
|
||||
|
||||
|
||||
TIMEZONE
|
||||
--------
|
||||
|
||||
This variable controls the system as well as service timezone for the Devilbox's own containers.
|
||||
This is especially useful to keep PHP and database timezones in sync.
|
||||
|
||||
+-----------------------+----------------+-------------------+
|
||||
| Name | Allowed values | Default value |
|
||||
+=======================+================+===================+
|
||||
| ``TIMEZONE`` | valid timezone | ``Europe/Berlin`` |
|
||||
+-----------------------+----------------+-------------------+
|
||||
|
||||
Have a look at Wikipedia to get a list of valid timezones: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
|
||||
|
||||
.. 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).
|
||||
@ -35,6 +35,23 @@ You can verifiy that the path is actually ``./data/www/`` by checking your ``.en
|
||||
|
||||
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
|
||||
-----------------
|
||||
|
||||
@ -52,6 +69,7 @@ You can verifiy that the docroot directory is actually ``htdocs`` by checking yo
|
||||
|
||||
HTTPD_DOCROOT_DIR=htdocs
|
||||
|
||||
|
||||
Domain suffix
|
||||
-------------
|
||||
|
||||
@ -68,46 +86,46 @@ You can verifiy that the suffix is actually ``loc`` by checking your ``.env`` fi
|
||||
TLD_SUFFIX=loc
|
||||
|
||||
|
||||
Make sense of it
|
||||
----------------
|
||||
Making sense of it
|
||||
------------------
|
||||
|
||||
Ok, let's sum it up and make sense of the previously provided information:
|
||||
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 |
|
||||
+===============+=================================+
|
||||
| data dir | ``./data/www`` |
|
||||
+---------------+---------------------------------+
|
||||
| project dir | ``./data/www/project-1`` |
|
||||
+---------------+---------------------------------+
|
||||
| docroot dir | ``./data/www/project-1/htdocs`` |
|
||||
+---------------+---------------------------------+
|
||||
| domain suffix | ``loc`` |
|
||||
+---------------+---------------------------------+
|
||||
| project url | ``http://project-1.loc`` |
|
||||
+---------------+---------------------------------+
|
||||
+---------------+---------------------------------+-------------------------------------------------------------+
|
||||
| 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
|
||||
^^^^^^^^
|
||||
**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`` in for each of your projects.
|
||||
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
|
||||
^^^^^^^^^^^
|
||||
**project dir**
|
||||
|
||||
A directory created in ``data dir``. This represents one project. By creating this directory, the `httpd` container automatically create a new VirtualHost that is ready to serve.
|
||||
Is your project and used to generate the virtual host together with the domain suffix.
|
||||
|
||||
The `httpd` container also uses the name of the ``data dir`` and the ``domain suffix`` to create the final url for the project.
|
||||
**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.
|
||||
|
||||
|
||||
docroot dir
|
||||
^^^^^^^^^^^
|
||||
|
||||
A directory inside your ``project dir`` from where the webserver will actually serve your files.
|
||||
|
||||
.. _project_creation_workflow:
|
||||
|
||||
Project creation workflow
|
||||
|
||||
@ -100,7 +100,11 @@ The ``.env`` file does nothing else then providing environment variables for ``D
|
||||
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/>`_
|
||||
.. 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
|
||||
|
||||
|
||||
Adjust ``.env`` file
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user