Documentation: Docker logs

docker-compose.yml

@@ -77,10 +77,10 @@ services:
 
     environment:
       ##
-      ## Debug?
+      ## Debug/Logging
       ##
       - DEBUG_COMPOSE_ENTRYPOINT
-      - DOCKER_LOGS=0
+      - DOCKER_LOGS
 
       ##
       ## UserID and GroupID
@@ -163,10 +163,11 @@ services:
     environment:
 
       ##
-      ## Debug?
+      ## Debug/Logging
       ##
       - DEBUG_ENTRYPOINT=${DEBUG_COMPOSE_ENTRYPOINT}
       - DEBUG_RUNTIME=${DEBUG_COMPOSE_ENTRYPOINT}
+      - DOCKER_LOGS
 
       ##
       ## Adjust timezone

docs/configuration-files/env-file.rst

@@ -40,6 +40,85 @@ When set to ``0`` only warnings and errors are shown.
 +------------------------------+----------------+---------------+
 
 
+.. _env_docker_logs:
+
+DOCKER_LOGS
+-----------
+
+This variable controls the output of logs. Logs can either go to file and will be available
+under ``./logs/`` inside the Devilbox git directory or they can be forwarded to Docker logs
+and will then be send to stdout and stderr.
+
++-------------------+----------------+---------------+
+| Name              | Allowed values | Default value |
++===================+================+===============+
+| ``DOCKER_LOGS``   | ``1`` or ``0`` | ``0``         |
++-------------------+----------------+---------------+
+
+When ``DOCKER_LOGS`` is set to ``1``, output will go to Docker logs, otherwise if it is set to
+``0`` the log output will go to files under ``./logs/``.
+
+The ``./log/`` directory itself will contain subdirectories in the form ``<service>-<version>``
+which will then hold all available log files. 
+
+.. note::
+    Log directories do not exist until you start the Devilbox and will only be created for
+    the service versions you have enabled in ``.env``.
+
+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
+
+When you want to read logs sent to Docker logs, you can do so via the following command:
+
+.. 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::
+    Currently this is only implemented for PHP-FPM and HTTPD Docker container.
+    MySQL will always output its logs to file and all other official Docker container
+    always output to Docker logs.
+
+
 DEVILBOX_PATH
 -------------
 

docs/getting-started/create-your-first-project.rst

@@ -4,6 +4,10 @@
 Create your first project
 *************************
 
+.. important::
+    Ensure you have read :ref:`getting_started_directory_overview` to understand what is
+    going on under the hood.
+
 .. note::
 
      This section not only applies for one project, it applied for as many projects as you need.

docs/getting-started/read-log-files.rst

@@ -0,0 +1,94 @@
+.. _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

docs/index.rst

@@ -25,6 +25,7 @@ devilbox documentation
    getting-started/start-the-devilbox
    getting-started/directory-overview
    getting-started/create-your-first-project
+   getting-started/read-log-files
    getting-started/enter-the-php-container
 
 

env-example

@@ -21,6 +21,20 @@
 DEBUG_COMPOSE_ENTRYPOINT=1
 
 
+###
+### Log to file or Docker logs.
+###
+### Logging to file means log files are available under log/
+### on your host operating system.
+### Logging to Docker logs means log files are streamed to
+### stdout and stderr.
+###
+### 1: Log to Docker logs
+### 0: Log to file
+###
+DOCKER_LOGS=0
+
+
 ###
 ### Relative or absolute path to the devilbox repository.
 ### (Used as a prefix for all mount paths)