Update README with detailed usage and setup instructions

README.md

@@ -1,3 +1,89 @@
-# stalwart-simplelogin-middleware
+# Stalwart SimpleLogin Middleware
 
-Middleware to create Aliases in Stalwart using SimpleLogin API in Password Managers
+Middleware to create Aliases in Stalwart using the SimpleLogin API within Password Managers.
+
+## Overview
+
+This middleware provides functionality to manage email aliases using the Stalwart mail server and the SimpleLogin API.
+It supports **PostgreSQL** as the backend database. The middleware image is available as a Docker container.
+
+## Currently Tested Password Managers
+
+The middleware has been tested with the following password managers:
+
+- **Bitwarden**
+
+Other password managers might work, but have not been tested yet. Contributions to expand support or test compatibility
+are welcome.
+
+## Features
+
+- Integration with Stalwart mail server.
+- Supports SimpleLogin API.
+- Backend database support with PostgreSQL.
+- Built-in connection pooling for PostgreSQL.
+
+## Getting Started
+
+### Prerequisites
+
+- Docker installed on your local machine or server.
+- PostgreSQL database.
+- Stalwart Mail server URI and API key for connecting with the mail server.
+
+### Pull Docker Image
+
+To use the middleware, pull the Docker image from the given registry:
+
+```bash
+docker pull git.spgrn.com/seang96/stalwart-simplelogin-middleware-web:latest
+```
+
+### API Key Permissions for Mail Server
+
+The **Stalwart API key** used in the `MAIL_SERVER_API_KEY` environment variable must have **the following permissions
+set to "On"**:
+
+- **View list of mailing lists**
+- **Create new mailing lists**
+- **Create new principals**
+- **Authenticate**
+
+Ensure the API key is properly configured with these permissions.
+
+### Environment Variables
+
+Before running the middleware, you need to configure the following environment variables:
+
+| Environment Variable     | Description                                    | Required |
+|--------------------------|------------------------------------------------|----------|
+| `MAIL_SERVER_URI`        | URI for the mail server.                       | Yes      |
+| `MAIL_SERVER_API_KEY`    | API key to authenticate with the mail server.  | Yes      |
+| `POSTGRES_URL`           | Connection string for the PostgreSQL database. | Yes      |
+| `POSTGRES_MIN_POOL_SIZE` | Minimum connections in the PostgreSQL pool.    | No       |
+| `POSTGRES_MAX_POOL_SIZE` | Maximum connections in the PostgreSQL pool.    | No       |
+
+Set these variables appropriately either as environment variables in your shell, in a `.env` file, or directly pass them
+when running the Docker container.
+
+### Running the Middleware
+
+Run the following command to start the middleware container, replacing `<value>` placeholders with your specific
+configuration:
+
+```bash
+docker run -e MAIL_SERVER_URI=<value> \
+           -e MAIL_SERVER_API_KEY=<value> \
+           -e POSTGRES_URL=<value> \
+           git.spgrn.com/seang96/stalwart-simplelogin-middleware-web:latest
+```
+
+### Admin API Key
+
+On the initial startup of the middleware, an admin API key is **automatically generated** and printed to the console.
+Make sure to **securely save this key**, as it is required for administrative operations.
+
+## License
+
+This project is licensed under the **GNU Affero General Public License v3.0** (AGPL-3.0).  
+You can find the full license text in the `LICENSE` file.