fix(docs): improve formatting and add missing command

README.md

@@ -1,33 +1,42 @@
 # LUMI 2
 
 **Lumi2** is the *LDAP user management interface*, a minimalistic web-ui for managing simple LDAP authentication backends.
+
 It lets an administrator create/read/update/delete users and groups in a user-friendly interface:
 
 ![Demo](/docs/demo.gif)
 
-Lumi2 eliminates the need for complex LDAP frontends, such as [PhpLdapAdmin](https://phpldapadmin.sourceforge.net/wiki/index.php/Main_Page), or modifying the DIT (directory information tree) through LDIF files.
+Lumi2 eliminates the need for complex LDAP frontends, such as [PhpLdapAdmin](https://phpldapadmin.sourceforge.net/wiki/index.php/Main_Page),
+or modifying the DIT (directory information tree) through LDIF files.
+
 It is quite opinionated and suitable only for small-scale deployments (such as a homelab or small enterprise), but it works really well there!
+
 Lumi2 can be used with an existing LDAP deployment, but it makes some [core assumptions](#assumptions-and-limitations) about the DIT it works on.
-If you are deploying Lumi2 alongside a fresh LDAP instance, it will create the necessary DIT entries for you.
 
 # Deployment
 
 Lumi2 is designed for use and deployment in a microservice environment.
-It works well together with a dockerized LDAP server (such as [osixia's OpenLDAP image](https://github.com/osixia/docker-openldap)), and you can use the included `docker-compose.yml` as a reference.
+
+It works well together with a dockerized LDAP server (such as [osixia's OpenLDAP image](https://github.com/osixia/docker-openldap)),
+and you can use the included `docker-compose.yml` as a reference.
+If you are deploying Lumi2 alongside a fresh LDAP instance of the osixia OpenLDAP image,
+everything works out of the box and you won't ever need to modify your LDAP entries directly.
 
 ## Assumptions and limitations
 
 Currently, the connection between Lumi2 and your LDAP server **does not encrypt traffic** using TLS.
-Your Lumi2 instance and the LDAP server it manages should run on the same host, otherwise it will be possible for a man-in-the-middle to read your user's credentials and personal information.
+Your Lumi2 instance and the LDAP server it manages should run on the same host, otherwise it will be possible for a man-in-the-middle to
+read your user's credentials and personal information.
 
 Lumi2 is simplistic and makes some assumptions about the structure of your LDAP DIT.
 The DIT hierarchy it expects (or creates) looks like this:
 
 ![LDAP DIT structure](/docs/ldap-dit-structure.svg)
 
-You should be aware of this structure when configuring other applications to use your LDAP backend.
-If you point Lumi2 at an existing LDAP server, make sure its DIT has this structure, otherwise Lumi2 will not work with your LDAP instance.
 When deploying a new LDAP server, you don't need to pay too much attention to the rest of this section, as Lumi2 will create the DIT entries for you as necessary.
+You should, however, be aware of this structure when configuring other applications to use your LDAP backend.
+
+If you point Lumi2 at an existing LDAP server, make sure its DIT matches the structure shown above and described below, otherwise Lumi2 will not work with your LDAP instance.
 
 ### Users
 
@@ -58,8 +67,11 @@ The groupname (`cn`) can contain only latin characters.
 
 ## Configuration
 
-Your Lumi2 instance is configured using the `config.py` python file. Edit the file accordingly so that Lumi2 can connect to your LDAP server and bind to it with admin credentials.
+Your Lumi2 instance is configured using the `config.py` python file.
+Customize the file so that Lumi2 can connect to your LDAP server and bind to it with admin credentials.
+
 Make sure you configure a secure `SECRET_KEY` and `ADMIN_PASSWORD` prior to deployment, as described below.
+
 It is recommended you use `docker-compose` for Lumi2 and your LDAP server. Use the `docker-compose.yml` and `config.py` files in this repo as a starting point for this.
 
 ### Security settings
@@ -68,7 +80,8 @@ To generate a secret key and a password hash, you first need to import some of L
 The easiest way to do this is by using a virtual environment. In the repo's root folder, run the following shell commands:
 
 ```bash
-python -m venv .venv
+python -m venv .venv 
+source .venv/bin/activate
 pip install -r requirements.txt
 ```
 
@@ -79,7 +92,7 @@ Generate a strong secret key now, by running the following command:
 python -c 'import secrets; print(secrets.token_hex())'
 ```
 
-Set the `SECRET_KEY` in your `config.py` to the random string you just generated.
+Replace the insecure `SECRET_KEY` in your `config.py` with the random string you just generated.
 
 Next, we need to replace the default password hash in `config.py` with a more secure one.
 Pick a **strong** password, which you will use later to log in to Lumi2, and generate its hash using the following command:
@@ -98,19 +111,43 @@ rm -rf .venv
 
 ### LDAP settings
 
-Lumi2 needs to know where to reach your LDAP server. This is set in the `LDAP_HOSTNAME` variable.
-What you put here depends on your environment, but if you are using `docker-compose` with both Lumi2 and OpenLDAP running in the same compose-stack, you can simply set the LDAP container's hostname here, optionally prefixed with `ldap://` and/or suffixed with the port on which the LDAP server is listening.
-By default, Lumi2 tries to connnect on 389, the standard LDAP port.
-**Important:** deploying Lumi2 alongside LDAP using `docker-compose` is highly recommended. Communication between Lumi2 and LDAP is currently not encrypted, so anyone listening to the network traffic between the two can read user information being exchanged between Lumi2 and your LDAP server.
+#### Connection settings
+
+Lumi2 needs to know where to reach your LDAP server. This is set in the `LDAP_HOSTNAME` variable.
+
+What you put here depends on your environment, but if you are using `docker-compose` with both Lumi2 and OpenLDAP running in the same compose-stack,
+you can simply set the LDAP container's hostname here.
+
+By default, Lumi2 tries to connnect on 389, the standard LDAP port, but you can specify a non-standard port as well.
+The following are all valid options:
+
+```python
+LDAP_HOSTNAME = 'myhost'
+
+LDAP_HOSTNAME = 'ldap.example.com:9000'
+
+LDAP_HOSTNAME = 'ldap://foo.bar.org'
+```
+
+**Important:** Communication between Lumi2 and LDAP is currently not encrypted, so anyone listening to the network traffic between the two can read user information being
+exchanged between Lumi2 and your LDAP server.
+Deploying Lumi2 alongside LDAP using `docker-compose` is therefor highly recommended.
+
+#### Bind user settings
+
+Provide the DN (distinguished name) and password for a user with read- and write-access to your LDAP server by setting the `LDAP_BIND_USER_DN` and `LDAP_BIND_USER_PASSWORD`
+variables respectively.
 
-Next, provide the DN (distinguished name) and password for a user with read- and write-access to your LDAP server by setting the `LDAP_BIND_USER_DN` and `LDAP_BIND_USER_PASSWORD` variables respectively.
 The `LDAP_BASE_DN` variable tells Lumi2 what the base DN (the root entry) of your LDAP server is called.
-The `LDAP_USERS_OU` and `LDAP_GROUPS_OU` variables tell Lumi2 under which OU users and groups can be found or created. Both must be direct children of the root entry.
+
+The `LDAP_USERS_OU` and `LDAP_GROUPS_OU` variables tell Lumi2 under which OU users and groups can be found or created.
+Both must be direct children of the root entry.
 If they do not exist yet on your LDAP server, they will be newly created by Lumi2 when it first starts.
 
 ### Logging
 
 By default, the lumi2 container logs HTTP access information to the console.
+
 You can additionally write the HTTP access logs to a file by specifying `LOG_FILE_PATH`.
 Note that the specified path points to *inside* the container, so if you want to persist access logs across container restarts, you should set up a Docker volume accordingly.
 Make sure the specified path is writeable by Lumi2.
@@ -121,10 +158,13 @@ To disable log rotation, leave the variable unspecified or set it to `0`.
 
 ## Running the server
 
-The `Dockerfile` and `docker-compose.yml` create a Lumi2 instance running behind a [waitress](https://docs.pylonsproject.org/projects/waitress/en/latest/) WSGI server, exposing the Lumi2 web interface on port 80.
+The `Dockerfile` and `docker-compose.yml` create a Lumi2 instance running behind a [waitress](https://docs.pylonsproject.org/projects/waitress/en/latest/) WSGI server,
+exposing the Lumi2 web interface on port 80.
 It is recommended to use a reverse proxy in front of the waitress server.
 
-Inside the container, Lumi2 and waitress are run by a non-root user. You can specify the `UID`/`GID` of this user by setting the `LUMI2_UID`/`LUMI2_GID` build arguments (see `docker-compose.yml` for reference).
+Inside the container, Lumi2 and waitress are run by a non-root user.
+You can specify the `UID`/`GID` of this user by setting the `LUMI2_UID`/`LUMI2_GID` build arguments (see `docker-compose.yml` for reference).
+
 You should make sure your `config.py` file persists across container restarts and is readable by the container's non-root user.
 The `LUMI2_CONFIG` environment variable is necessary to tell Lumi2 where `config.py` can be found inside the container.
 
@@ -136,7 +176,8 @@ sudo docker-compose up -d --build
 
 # Development
 
-Lumi2 is a python application, built using the Flask framework. The following frameworks and/or libraries are also used:
+Lumi2 is a python application, built using the Flask framework.
+The following frameworks and/or libraries are also used:
 
 - Backend:
     - [Flask](https://flask.palletsprojects.com/en/2.2.x/) - a python web framework