[Doc] readme update

2026-08-03 21:44:09 +02:00
parent dc50e422ba
commit fc84ded0c6
1 changed files with 68 additions and 2 deletions
@@ -1,3 +1,69 @@
-# Flask LDAP user management
+# LUSER

-Web app that allows users to add,remove and change passwords in LDAP system
+A lightweight user management system for LDAP, implemented using Flask. This application provides a web interface for users to register, change passwords, and unregister themselves from an LDAP directory.
+
+## Features
+
+- **User Registration**: New users can create an account with a captcha to prevent automated registrations.
+- **Password Management**: Users can change their LDAP passwords securely.
+- **User Unregistration**: Users can remove themselves from the LDAP system.
+- **Captcha Protection**: Uses a custom captcha mechanism to mitigate bot registrations.
+- **LDAP Integration**: Directly interacts with LDAP for all credential and user management tasks.
+
+## Prerequisites
+
+- Python 3.x
+- LDAP Server
+- `passlib` for secure password hashing
+- `Flask` for the web framework
+
+## Installation
+
+1. **Clone the repository**:
+   ```bash
+   git clone <repository-url>
+   cd luser
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Configure the application**:
+   Edit the `config.ini` file to provide your LDAP server details and paths:
+   - `LDAPHOST`: Address of your LDAP server.
+   - `LDAPADMINNAME`: Admin username for LDAP operations.
+   - `LDAPPASS`: Admin password for LDAP operations.
+   - `USERBASE`: The base DN for users.
+   - `CAPTCHA_PATH`: Path where captcha images are stored.
+
+4. **Setup Captcha script**:
+   Ensure the `captcha.sh` script is available in `/usr/local/bin/` and is executable.
+
+## Running the Application
+
+You can run the application using the provided `run.py` script:
+
+```bash
+python run.py
+```
+
+The application will be available at `http://localhost:5000` (or the port specified in your configuration).
+
+## Project Structure
+
+- `luser/`: Main application package.
+    - `routes.py`: Defines the web endpoints and business logic.
+    - `models.py`: Handles LDAP interactions.
+    - `templates/`: HTML templates for the web interface.
+    - `static/`: Static files (CSS, etc.).
+- `build-deb/`: Contains instructions and files for building a Debian package.
+- `run.py`: Entry point for the Flask application.
+- `config.ini`: Configuration file for LDAP and system settings.
+
+## Security Considerations
+
+- This application uses `ldap_salted_sha1` for password hashing.
+- Ensure the LDAP connection is secured (e.g., via LDAPS) in production environments.
+- The captcha mechanism is implemented to prevent automated registration attempts.