From 83e1ff4ec7a932035286dce8e3e40e885b47e321 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=C3=A6Ltorio?= <aeltorio@universidadatlantico.org>
Date: Sun, 1 Sep 2024 13:47:00 +0200
Subject: [PATCH] chore: Update nginx-ad-auth documentation and Dockerfile for
 better usability

---
 README.md | 82 +++++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 64 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 59ff3cd..61f3882 100644
--- a/README.md
+++ b/README.md
@@ -1,33 +1,73 @@
 # nginx-ad-auth
 
-`nginx-ad-auth` is a Go program that serves as an authentication service for the NGINX email plugin. It authenticates users against Active Directory using LDAP.
+`nginx-ad-auth` is a Go-based authentication service for the NGINX email proxy, allowing seamless authentication of users against Active Directory using LDAP. It integrates easily with NGINX to secure email services (IMAP, SMTP, POP3), leveraging existing AD infrastructures.
 
 ## Features
 
-- Listens on a configurable HTTP port
-- Authenticates users against Active Directory
-- Supports IMAP, POP3, and SMTP protocols
-- Configurable via command-line flags or environment variables
+- **Easy Integration:** Connects with NGINX mail proxy for seamless user authentication.
+- **Supports Multiple Protocols:** IMAP, POP3, and SMTP protocols supported for full compatibility.
+- **Active Directory Authentication:** Authenticate users against AD using LDAP.
+- **Flexible Configuration:** Configure through command-line flags or environment variables.
+- **Lightweight:** Minimal dependencies, runs as a standalone service.
+
+## Table of Contents
+
+- [nginx-ad-auth](#nginx-ad-auth)
+  - [Features](#features)
+  - [Table of Contents](#table-of-contents)
+  - [TD;DR](#tddr)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+    - [Test](#test)
+  - [Usage](#usage)
+    - [Flags](#flags)
+    - [Environment Variables](#environment-variables)
+  - [Docker](#docker)
+  - [Kubernetes](#kubernetes)
+  - [Using the Helm Chart](#using-the-helm-chart)
+  - [Configuring NGINX as an Email Proxy](#configuring-nginx-as-an-email-proxy)
+  - [License](#license)
+    - [Key points of the AGPLv3](#key-points-of-the-agplv3)
+  - [Contributing](#contributing)
+  - [Support](#support)
+
+## TD;DR
+
+You can run `nginx-ad-auth` using Docker in just a few steps:
+
+```bash
+docker run -p 8080:8080 \
+   -e NGINX_AUTH_LDAP_URI="ldap://your-ad-server" \
+   -e NGINX_AUTH_LDAP_BASE="dc=your,dc=domain" \
+   -e NGINX_AUTH_AD_DOMAIN="your-domain" \
+   -e NGINX_AUTH_MAIL_SERVER="your-mail-server" \
+   -e NGINX_AUTH_MAIL_SERVER_PORT=143 \
+   sctg/nginx-ad-auth
+```
 
 ## Prerequisites
 
-- Go 1.21 or later
+- Go 1.21 or later [(Go installation guide)](https://golang.org/doc/install)
 - Access to an Active Directory server
+- Docker installed for the Docker setup (optional).
 
 ## Installation
 
 1. Clone the repository:
-   ```
+
+   ```bash
    git clone https://github.com/yourusername/nginx-ad-auth.git
    ```
 
 2. Change to the project directory:
-   ```
+
+   ```bash
    cd nginx-ad-auth
    ```
 
 3. Build the program:
-   ```
+
+   ```bash
    go build -o nginx-ad-auth
    ```
 
@@ -44,7 +84,7 @@ VALIDUSER="myuser" CORRECTPASSWORD="mypassword" tests/test-nginx-ad-auth.sh
 
 Run the program with the following command:
 
-```
+```bash
 ./nginx-ad-auth [flags]
 ```
 
@@ -73,14 +113,16 @@ You can also use environment variables instead of flags:
 
 To build and run the Docker image:
 
-1. Build the image:
-   ```
+1. (Optional) Build the image:
+
+   ```bash
    docker build -t nginx-ad-auth .
    ```
 
 2. Run the container:
-   ```
-   docker run -p 8080:8080 -e NGINX_AUTH_LDAP_URI=ldap://your-ad-server nginx-ad-auth
+
+   ```bash
+   docker run -p 8080:8080 -e NGINX_AUTH_LDAP_URI=ldap://your-ad-server -e NGINX_AUTH_LDAP_BASE="dc=your,dc=domain" -e NGINX_AUTH_AD_DOMAIN=your-domain -e NGINX_AUTH_MAIL_SERVER="your-mail-server" -e NGINX_AUTH_MAIL_SERVER_PORT=143 sctg/nginx-ad-auth
    ```
 
 ## Kubernetes
@@ -98,17 +140,20 @@ To deploy the `nginx-ad-auth` service using the provided Helm chart, follow thes
    - `env`: Update the environment variables to match your Active Directory and mail server configuration.
 
 3. From the root of the project, run:
-   ```
+
+   ```bash
    helm install nginx-ad-auth ./helm/nginx-ad-auth
    ```
 
 4. To upgrade an existing deployment with new values:
-   ```
+
+   ```bash
    helm upgrade nginx-ad-auth ./helm/nginx-ad-auth
    ```
 
 5. You can customize the installation by overriding values:
-   ```
+
+   ```bash
    helm install nginx-ad-auth ./helm/nginx-ad-auth --set replicaCount=3
    ```
 
@@ -134,6 +179,7 @@ mail {
 ```
 
 This configuration does the following:
+
 - Sets up NGINX to listen on port 993 for IMAPS connections.
 - Uses the `nginx-ad-auth` service running on `localhost:8080` for authentication.
 - Proxies authenticated connections to the internal mail server at 192.168.1.1:143.
@@ -166,4 +212,4 @@ Contributions are welcome! Please feel free to submit a Pull Request.
 
 ## Support
 
-If you encounter any problems or have any questions, please open an issue in the GitHub repository.
\ No newline at end of file
+If you encounter any problems or have any questions, please open an issue in the GitHub repository.