Add LDAP docker configuration.

admin-manual/customization/authentication.rst

@@ -139,20 +139,31 @@ Enabling LDAP authentication
 
 .. _LDAP: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol
 
-AtoM can also be configured to authenticate users using (`LDAP`_ ), an "open, 
+AtoM can also be configured to authenticate users using `LDAP`_, an "open,
 vendor-neutral, industry standard application protocol for accessing and 
 maintaining distributed directory information services over an Internet 
 Protocol (IP) network" (Wikipedia). When this is enabled, users attempting to 
 log in will use the credentials associated with their LDAP account, instead 
 of local account credentials, when :ref:`logging in <log-in>` to AtoM. 
 
-Enabling LDAP authentication in AtoM requires manually editing a few AtoM 
-configuration files. For more general information on how to do this, see
-:ref:`Manage AtoM configuration files <customization-config-files>`.
+.. IMPORTANT::
+
+   To enable LDAP authentication in AtoM, manually installing the ``php-ldap``
+   extension is required.
+
+Enabling LDAP authentication in AtoM requires manually installing the LDAP extension
+and editing a few AtoM configuration files. For more general information on how
+to do this, see :ref:`Manage AtoM configuration files <customization-config-files>`.
+
+First, we'll need to make install the php LDAP extension:
+
+.. code-block:: bash
+
+   sudo apt-get install php-ldap
 
-First, we'll need to make a small change in the ``config/factories.yml`` 
-configuration file. You can open this file with ``nano`` or another text editor 
-to make the changes. Starting from AtoM's root installation directory, run: 
+Next, make a small change in the ``config/factories.yml`` configuration file.
+You can open this file with ``nano`` or another text editor to make the changes.
+Starting from AtoM's root installation directory, run:
 
 .. code-block:: bash
 
@@ -191,8 +202,7 @@ Change the ``myUser`` value to ``ldapUser``:
     user:
       class: ldapUser
 
-Exit and save your changes, and the clear the application cache and restart 
-PHP-FPM.
+Exit and save your changes, then clear the application cache and restart PHP-FPM.
 
 * :ref:`maintenance-clear-cache`
 * :ref:`troubleshooting-restart-php-fpm`

dev-manual/env/compose.rst

@@ -4,6 +4,10 @@
 Docker Compose
 ==============
 
+.. |gears| image:: images/gears.png
+   :height: 18
+   :width: 18
+
 Linux containers and Docker have radically changed the way applications are
 developed, built, distributed and deployed. The AtoM team is experimenting
 with new workflows that make use of containers. This document introduces our
@@ -90,6 +94,10 @@ It's time to use Docker Compose in order to provision our containers:
    latest version before creating the containers. It has to be based on Alpine
    v3.8 or higher to be able to install some packages.
 
+.. NOTE::
+
+   To enable LDAP authentication with Docker, please skip to :ref:`docker-ldap-auth`.
+
 .. code-block:: bash
 
    # Create and start containers. This may take a while the first time you run
@@ -195,6 +203,112 @@ stop and remove related containers, network and volumes by running:
 
    docker-compose down --volumes
 
+.. _docker-ldap-auth:
+
+LDAP Authentication
+===================
+
+Docker Configuration
+++++++++++++++++++++
+
+To enable LDAP authentication using docker, we need to create two new files and
+update the existing ``docker-compose.dev.yml`` file. These files are required to
+create a network for LDAP and to configure users for LDAP.
+
+First, create a custom network for authentication in a new file called
+``docker-compose.auth-network.yml`` and put it in the ``docker`` directory. Copy the
+following into the file:
+
+.. code-block:: bash
+
+   networks:
+      default:
+         name: auth-network
+         external: true
+
+Then set up docker compose to use the new network by appending the following to
+the end of the existing ``docker-compose.dev.yml`` file:
+
+.. code-block:: bash
+
+   networks:
+      auth-network:
+         name: auth-network
+
+Lastly, configure LDAP credentials in a LDAP Data Interchange Format (LDIF) file,
+let's call it ``config-ldap.ldif``. The following example creates 1 user, ``example``, with
+Administrator permissions. Please refer to the
+`LDAP documentation <https://ldap.com/ldif-the-ldap-data-interchange-format/>`__ for more help.
+
+.. code-block:: bash
+
+   dn: cn=example,ou=People,dc=example,dc=org
+   objectClass: person
+   objectClass: inetOrgPerson
+   sn: example
+   cn: example
+   mail: example@example.com
+   userpassword: example
+
+   dn: ou=Groups,dc=example,dc=org
+   objectClass: organizationalUnit
+   ou: Groups
+
+   dn: cn=Administrator,ou=Groups,dc=example,dc=org
+   objectClass: groupOfNames
+   cn: Administrator
+   member: cn=example,ou=People,dc=example,dc=org
+
+Finally, we can start AtoM using ``auth-network``:
+
+``docker compose -f docker-compose.yml -f docker/docker-compose.auth-network.yml up -d``
+
+AtoM Configuration
+++++++++++++++++++
+
+.. SEEALSO::
+
+   * :ref:`ldap-enabling`
+
+To enable LDAP Authentication, change the ``myUser`` value to ``ldapUser`` in
+``config/factories.yml``:
+
+.. code-block:: bash
+
+    user:
+      class: ldapUser
+
+Clear cache and restart ``atom_worker`` for the changes to appear. After doing so,
+a new configuration section will be available in |gears| **Admin > Settings**,
+where you can define your LDAP authentication settings:
+
+.. image:: images/ldap-config.*
+   :align: center
+   :width: 90%
+   :alt: An image of the LDAP authentication settings
+
+To determine the Host IP for this example based on your docker configuration, run
+``docker inspect auth-network`` to determine the Host IP (``IPv4Address``) used
+for ``openldap``.
+
+.. NOTE::
+
+   The Host IP value is dynamic and may be different each time.
+
+Other values that we will use for this example are as follows:
+
+    - Port: 389
+    - Base DN: ou=People,dc=example,dc=org
+    - Bind Lookup Attribute: cn
+
+.. NOTE::
+
+   Although we've defined the openldap port to ``1389`` in ``docker-compose.dev.yml``,
+   ``LDAP_PORT`` should still be running on port ``389``. This can be confirmed
+   by running ``docker compose logs openldap``, and you should be able to see the
+   defined ``LDAP_PORT``.
+
+
 Connect to AtoM
 ===============