Documentation: SSL Certificates

docs/configuration-files/env-file.rst

@@ -423,6 +423,34 @@ and report as unsuccessful. The default is ``1`` second, wich should be fairly s
 +-----------------------+----------------+-------------------+
 
 
+.. _env_devilbox_ui_ssl_cn:
+
+DEVILBOX_UI_SSL_CN
+------------------
+
+When accessing the Devilbox intranet via ``https`` it will use an automatically created SSL certificate.
+Each SSL certificate requires a valid Common Name, which must match the virtual host name.
+
+This setting let's you specify by what **name** you are accessing the Devilbox intranet.
+The default is ``localhost``, but if you have created your own alias, you must change this value
+accordingly. Also note that multiple values are possible and must be separated with a comma.
+When you add an asterisk (``*.``) to the beginning, it means it will create a wildcard certificate for that
+hostname.
+
++-------------------------+------------------------------+-----------------------------------------------+
+| Name                    | Allowed values               | Default value                                 |
++=========================+==============================+===============================================+
+| ``DEVILBOX_UI_SSL_CN``  | comma separated list of CN's | ``localhost,*.localhost,devilbox,*.devilbox`` |
++-------------------------+------------------------------+-----------------------------------------------+
+
+**Examples**:
+
+* ``DEVILBOX_UI_SSL_CN=localhost``
+* ``DEVILBOX_UI_SSL_CN=localhost,*.localhost``
+* ``DEVILBOX_UI_SSL_CN=localhost,*.localhost,devilbox,*.devilbox``
+* ``DEVILBOX_UI_SSL_CN=intranet.example.com``
+
+
 .. _env_devilbox_ui_protect:
 
 DEVILBOX_UI_PROTECT
@@ -458,13 +486,13 @@ password by which it will be protected.
 +--------------------------+----------------+-------------------+
 
 
-.. _env_devilbox_ui_disable:
+.. _env_devilbox_ui_enable:
 
-DEVILBOX_UI_DISABLE
+DEVILBOX_UI_ENABLE
 -------------------
 
 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``.
+you need to set this variable to ``0``.
 
 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
@@ -473,7 +501,7 @@ ordering their names alphabetically.
 +-------------------------+----------------+-------------------+
 | Name                    | Allowed values | Default value     |
 +=========================+================+===================+
-| ``DEVILBOX_UI_DISABLE`` | ``0`` or ``1`` | ``0``             |
+| ``DEVILBOX_UI_ENABLE``  | ``0`` or ``1`` | ``1``             |
 +-------------------------+----------------+-------------------+
 
 
@@ -990,6 +1018,19 @@ else if 80 is already in use on your host operating system.
 +----------------------+-------------------+------------------+
 
 
+HOST_PORT_HTTPD_SSL
+-------------------
+
+The port to expose for the web server (Apache or Nginx) for HTTPS (SSL) requests. This is usually
+443. Set it to something else if 443 is already in use on your host operating system.
+
++--------------------------+-------------------+------------------+
+| Name                     | Allowed values    | Default value    |
++==========================+===================+==================+
+| ``HOST_PORT_HTTPD_SSL``  | ``1`` - ``65535`` | ``443``           |
++--------------------------+-------------------+------------------+
+
+
 HOST_PORT_MYSQL
 ---------------
 

docs/configuration-global/https-ssl.rst

@@ -0,0 +1,104 @@
+.. _configuration_https_ssl:
+
+***********
+HTTPS (SSL)
+***********
+
+This page shows you how to use the Devilbox on https and how to import the Certificate Authority
+into your browser once, so that you always and automatically get valid SSL certificates for all new
+projects.
+
+SSL certificates are generated automatically and there is nothing to do from your side.
+
+.. image:: /_static/img/global-configuration/https-ssl-address-bar.png
+
+**Table of Contents**
+
+.. contents:: :local:
+
+
+TL;DR
+=====
+
+Import the Certificate Authority into your browser and you are all set.
+
+
+How does it work
+================
+
+Certificate Authority
+---------------------
+
+When the Devilbox starts up for the first time, it will generate a
+`Certificate Authority <https://en.wikipedia.org/wiki/Certificate_authority>`_ and will store its
+public and private key in ``./ca/`` within the Devilbox git directory.
+
+The keys are only generated if they don't exist and kept permanently if you don't delete them
+manually, i.e. they are not overwritten.
+
+.. code-block:: bash
+
+    host> cd path/to/devilbox
+    host> ls -l ca/
+    -rw-r--r--  1 cytopia cytopia 1558 May  2 11:12 devilbox-ca.crt
+    -rw-------  1 cytopia cytopia 1675 May  2 11:12 devilbox-ca.key
+    -rw-r--r--  1 cytopia cytopia   17 May  4 08:35 devilbox-ca.srl
+
+
+SSL Certificates
+----------------
+
+Whenever you create a new project directory, multiple things happen in the background:
+
+1. A new virtual host is created
+2. DNS is provided via :ref:`global_configuration_auto_dns`
+3. A new SSL certificate is generated for that vhost
+4. **The SSL certificate is signed by the Devilbox Certificate Authority**
+
+By having a SSL certificates signed by the provided CA, you will only have to import the CA
+into your browser ones and all current projects and future projects will automatically have
+valid and trusted SSL certificates without any further work.
+
+.. important::
+    Importing the CA into the browser is also recommended and required for the Devilbox
+    intranet page to work properly.
+
+
+Import the CA into your browser
+===============================
+
+Chrome / Chromium
+-----------------
+
+Open Chrome settings, scroll down to the very bottom and click on ``Advanced`` to expand the
+advanced settings.
+
+.. image:: /_static/img/global-configuration/https-ssl-01-settings.png
+
+Find the setting ``Manage certificates`` and open it.
+
+.. image:: /_static/img/global-configuration/https-ssl-02-advanced-settings.png
+
+Navigate to the tab setting ``AUTHORITIES`` and click on ``IMPORT``.
+
+.. image:: /_static/img/global-configuration/https-ssl-03-authorities.png
+
+Select ``devilbox-ca.crt`` from within the Devilbox ``./ca`` directory:
+
+.. image:: /_static/img/global-configuration/https-ssl-04-import.png
+
+As the last step you are asked what permissions you want to grant the newly importat CA.
+To make sure it works everywhere, check all options and proceed with ``OK``.
+
+.. image:: /_static/img/global-configuration/https-ssl-05-set-trust.png
+
+Now you are all set and all generated SSL certificates will be valid from now on.
+
+.. image:: /_static/img/global-configuration/https-ssl-address-bar.png
+
+
+
+Further Reading
+===============
+
+.. seealso:: ``.env`` variable: :ref:`env_devilbox_ui_ssl_cn`

docs/getting-started/the-intranet.rst

@@ -125,7 +125,7 @@ When the intranet is disabled, there is no way to access it.
 .. seealso::
     In order to do so, have a look at the following ``.env`` variable:
 
-    * :ref:`env_devilbox_ui_disable`
+    * :ref:`env_devilbox_ui_enable`
 
 
 Checklist

docs/index.rst

@@ -110,6 +110,7 @@ host is ready to be served with your custom domain.
    :caption: Global configuration
    :maxdepth: 2
 
+   configuration-global/https-ssl
    configuration-global/webserver
    configuration-global/php
    configuration-global/mysql