From 4502497371a903b7288c767aaf8c0974c984253c Mon Sep 17 00:00:00 2001 From: cytopia Date: Mon, 2 Apr 2018 13:45:53 +0200 Subject: [PATCH] Documentation: Docker logs --- docker-compose.yml | 7 +- docs/configuration-files/env-file.rst | 79 ++++++++++++++++ .../create-your-first-project.rst | 4 + docs/getting-started/read-log-files.rst | 94 +++++++++++++++++++ docs/index.rst | 1 + env-example | 14 +++ 6 files changed, 196 insertions(+), 3 deletions(-) create mode 100644 docs/getting-started/read-log-files.rst diff --git a/docker-compose.yml b/docker-compose.yml index 43c2069d..041ff649 100644 --- a/docker-compose.yml +++ b/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 diff --git a/docs/configuration-files/env-file.rst b/docs/configuration-files/env-file.rst index b01a2b29..d786e3eb 100644 --- a/docs/configuration-files/env-file.rst +++ b/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 ``-`` +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 + │   ├── -access.log # Each project has its own access log + │   ├── -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 ------------- diff --git a/docs/getting-started/create-your-first-project.rst b/docs/getting-started/create-your-first-project.rst index ea5f2998..75c96088 100644 --- a/docs/getting-started/create-your-first-project.rst +++ b/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. diff --git a/docs/getting-started/read-log-files.rst b/docs/getting-started/read-log-files.rst new file mode 100644 index 00000000..0de60549 --- /dev/null +++ b/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/-/`` + +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 + │   ├── -access.log # Each project has its own access log + │   ├── -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 diff --git a/docs/index.rst b/docs/index.rst index 902439b4..c89c4646 100644 --- a/docs/index.rst +++ b/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 diff --git a/env-example b/env-example index 5fe7c84d..bd860b3e 100644 --- a/env-example +++ b/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)