Some liddle doc changes

README.md

@@ -39,7 +39,8 @@ Modern enterprises face increasing security challenges with generally distribute
 **Centralized Control Across Distributed Fail2Ban Instances**
 
 - **Unified Dashboard**: Monitor and manage multiple Fail2Ban servers from a single interface
-- **Flexible Connectivity**: Support for local, SSH, and API agent connections form Fail2Ban-UI to other Fail2Ban Instances
+- **Flexible Connectivity**: Support for local, SSH, (and API agent) connections from Fail2Ban-UI to Fail2Ban Instances
+- **API Agent Connector**: Technical preview; Basic API functionality available, full implementation in progress
 - **Connection Testing**: Validate backend connectivity before activate them on the management UI
 
 **Use Cases:**
@@ -53,7 +54,9 @@ Modern enterprises face increasing security challenges with generally distribute
 
 - **Live Event Monitoring**: Real-time ban events from all configured / connected servers
 - **Historical Analysis**: SQLite-based event storage with advanced querying
-- **Geographic Intelligence**: Country-based threat analysis and visualization (Will be later send to SIEM - planned)
+- **Geographic Intelligence**: Country-based threat analysis and visualization with GeoIP and whois lookups (Option to send the logs to a SIEM is planned)
+- **Integrated Lookups**: Whois and GeoIP lookups are performed directly by Fail2Ban UI (no Linux binary dependencies anymore on fail2ban side)
+- **Smart Log Filtering**: Automatic selection of most relevant log lines for ban notifications
 - **Recurring Threat Detection**: Identify persistent attackers across time windows
 - **Ban Insights Dashboard**: Aggregated statistics
 - **Event Correlation**: Track attack patterns across multiple servers and jails (planned with Elasticsearch)
@@ -69,7 +72,7 @@ Modern enterprises face increasing security challenges with generally distribute
 
 - **Cross-Jail Search**: Find banned IPs across all active jails instantly
 - **Bulk Operations**: Manage multiple bans simultaneously
-- **Ban History**: Complete audit trail with timestamps, ban-reasons, and context like whois information of the attacker
+- **Ban History**: Complete audit trail with timestamps, ban-reasons, and context including whois and GeoIP information of the attacker
 - **Whitelist Management**: Configure trusted IPs and networks
 - **Automatic Unban**: Time-based ban expiration with configurable policies
 - **Permanent Ban for Reccuring IPs**: Set a threshold in the Settings, after what amount of Bans a IP is automatically banned permanently on Firewall (Currently Supported Mikrotik/PFSense)
@@ -89,8 +92,9 @@ Modern enterprises face increasing security challenges with generally distribute
 
 - **Multi-Language Email Alerts**: Localized notifications in currently 5 supported languages
 - **Country-Based Filtering**: Alert only on threats from specific geographic regions to reduce alert fatigue
+- **GeoIP Provider Selection**: Choose between MaxMind (needs a local database) or Built-in (ip-api.com) for geographic lookups
 - **SMTP Integration**: Support M365 Mail-Servers with STARTTLS
-- **Emai Templates**: Currentls features a Modern and classic email design (more to come)
+- **Email Templates**: Currently features a Modern and classic email design (more to come)
 - **Alert Aggregation**: This feature is planned for the SIEM-modul
 
 ### 🔐 Enterprise Security
@@ -221,7 +225,7 @@ Comprehensive settings management for alerts, advanced banning, and system prefe
 
 ### Technology Stack
 
-- **Backend**: Go 1.21+ (Golang)
+- **Backend**: Go 1.24+ (Golang)
 - **Frontend**: Vanilla JavaScript, Tailwind CSS
 - **Database**: SQLite (embedded)
 - **Container Runtime**: Podman/Docker compatible
@@ -236,11 +240,11 @@ Comprehensive settings management for alerts, advanced banning, and system prefe
 
 - **Operating System**: Linux (RHEL 8+, Ubuntu 20.04+, Debian 11+, or containerized)
 - **Fail2Ban**: At least version 0.10+ installed and configured
-- **Go**: Version 1.21+ (only for source builds)
+- **Go**: Version 1.24+ (only for source builds)
-- **Node.js**: Version 16+ (for Tailwind CSS builds)
+- **Node.js**: Version 16+ (only for source build - Tailwind CSS)
 - **Permissions**: Root access to configure FACL and sudo-rules and Fail2Ban socket access
 
-### Installation Methods
+### Installation Methods (Example with mounts for local fail2ban connector)
 
 #### Method 1: Container Deployment (Recommended for Production)
 
@@ -261,7 +265,6 @@ podman run -d \
   -v /etc/fail2ban:/etc/fail2ban:Z \
   -v /var/log:/var/log:ro \
   -v /var/run/fail2ban:/var/run/fail2ban \
-  -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
   registry.swissmakers.ch/infra/fail2ban-ui:latest
 ```
 
@@ -274,9 +277,9 @@ git clone https://github.com/swissmakers/fail2ban-ui.git
 cd fail2ban-ui
 
 # Build the image
-sudo podman build -t fail2ban-ui:latest .
+sudo podman build -t fail2ban-ui:dev .
 # or with Docker:
-sudo docker build -t fail2ban-ui:latest .
+sudo docker build -t fail2ban-ui:dev .
 
 # Run the container
 sudo podman run -d \
@@ -286,8 +289,7 @@ sudo podman run -d \
   -v /etc/fail2ban:/etc/fail2ban:Z \
   -v /var/log:/var/log:ro \
   -v /var/run/fail2ban:/var/run/fail2ban \
-  -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
+  localhost/fail2ban-ui:dev
-  fail2ban-ui:latest
 ```
 
 **Option C: Using Docker Compose**
@@ -296,9 +298,13 @@ For easier management, use Docker Compose:
 ```bash
 # Copy the example file
 cp docker-compose.example.yml docker-compose.yml
+# or
+cp docker-compose-allinone.example.yml docker-compose.yml
 
 # Edit docker-compose.yml to customize (e.g., change PORT)
 # Then start:
+podman compose up -d 
+# or
 docker-compose up -d
 ```
 
@@ -314,11 +320,10 @@ podman run -d \
   -v /etc/fail2ban:/etc/fail2ban:Z \
   -v /var/log:/var/log:ro \
   -v /var/run/fail2ban:/var/run/fail2ban \
-  -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
   registry.swissmakers.ch/infra/fail2ban-ui:latest
 ```
 
-Access the web interface at `http://localhost3080`.
+Access the web interface at `http://localhost:3080`.
 
 **Volume Mounts Explained**
 
@@ -327,10 +332,10 @@ Access the web interface at `http://localhost3080`.
 | `/config` | ✅ Yes | Stores SQLite database, application settings, and SSH keys for remote connections |
 | `/etc/fail2ban` | ✅ Yes* | Access to Fail2Ban configuration files (jails, filters, actions) |
 | `/var/run/fail2ban` | ✅ Yes* | Access to Fail2Ban control socket for local management |
-| `/var/log` | ⚠️ Optional | Read-only access to system logs for filter testing |
+| `/var/log` | ✅ Yes* | Read-Only | `:ro` | System log files for automated logpath tests on jail management. |
-| `/usr/share/GeoIP` | ⚠️ Optional | Read-only access to GeoIP databases for geographic analysis |
+| `/path/to/your/GeoIPFolder` | ⚠️ Optional | Read-Only | `:ro` | MaxMind GeoIP databases (only needed if using MaxMind provider) |
 
-*Required only if managing a local Fail2Ban instance. Not needed for remote-only deployments.
+*Required only if managing a local Fail2Ban instance as well. Not needed for remote-only deployments.
 
 **📖 [Complete Container Deployment Guide](./deployment/container/README.md)** - Detailed documentation including volume descriptions, SELinux configuration, and troubleshooting.
 
@@ -361,7 +366,7 @@ go build -o fail2ban-ui ./cmd/server/main.go
    - **Remote Server**: Add via SSH or API agent connection
 
 3. **Configure Settings**
-   - Set up email alerts (optional)
+   - Set up email alerts
    - Configure language preferences
    - Adjust security settings
 
@@ -384,15 +389,65 @@ go build -o fail2ban-ui ./cmd/server/main.go
 
 - **[SELinux Configuration](./deployment/container/SELinux/)**: Security policies for SELinux-enabled systems
 
-### Configuration
+### Connector Types
+
+Fail2Ban UI supports three types of connectors to manage remote and or local only Fail2Ban instances:
+
+#### Local Connector
+
+The local connector manages Fail2Ban on the same host/vm/container-stack where Fail2Ban UI runs. It does that by directly communicating with the local Fail2Ban instance via socked, without network overhead.
+
+**How it works:**
+- Accesses the Fail2Ban control socket at `/var/run/fail2ban/fail2ban.sock`
+- Reads and writes configuration files directly to `/etc/fail2ban/`
+- Requires FACL (File Access Control Lists) rules and passwordless sudo permissions to `/usr/bin/fail2ban-client` (if not running as privileged e.g. in a container)
+
+**When to use:**
+- ✅ Fail2Ban UI and Fail2Ban run on the same server
+- ✅ Single-server deployments
+- ✅ Development or testing environments
+- ✅ Maximum performance with zero network latency
+- ✅ Simplest setup with minimal configuration
+
+#### SSH Connector
+
+The SSH connector connects to remote Fail2Ban instances over SSH, enabling centralized management of distributed infrastructure. (no need to install fail2ban-UI everyware)
+
+**How it works:**
+- Establishes SSH connections to remote servers using key-based authentication
+- Transfers and manages configuration files encrypted over SSH
+- Automatically deploys custom Fail2Ban actions to remote instances for callback API ban-communication
+- Executes `fail2ban-client` commands remotely via SSH
+
+**When to use:**
+- ✅ Managing Fail2Ban instances on remote servers supporting SSH
+- ✅ Multi-server deployments across different hosts / reverse proxies
+- ✅ When Fail2Ban UI runs on a dedicated management server
+- ✅ Environments where direct socket access is not possible
+
+**Requirements:**
+- SSH key-based authentication (passwordless login)
+- Network connectivity from Fail2Ban UI host to remote server
+- Service account on remote server with appropriate permissions
+- Sudo access for Fail2Ban commands (configured via sudoers)
+- File system ACLs on remote server with write-permissions for `/etc/fail2ban/` directory
+
+#### API Agent Connector *(Technical Preview)*
+
+The API agent connector uses a lightweight agent installed on remote servers that communicates bouth ways, to and from Fail2Ban UI via REST API.
+
+**Status:** Implementation in progress
+
+### Configuration Values
 
 #### Fail2Ban Callback URL
 
-The **Fail2Ban Callback URL** is a critical setting that determines how Fail2Ban instances send ban alerts back to Fail2Ban UI. This URL is embedded in a custom Fail2Ban action file that gets deployed to all managed Fail2Ban instances (local, SSH, and API agent connections).
+The **Fail2Ban Callback URL** is a critical setting that determines how Fail2Ban instances send ban alerts back to Fail2Ban UI. This URL is embedded in a custom Fail2Ban action file as well as the secret that gets deployed to all managed Fail2Ban instances (both local and SSH). For the API agent connections, only the Callback URL and Secret is relevant.
 
 **How it works:**
-- When a Fail2Ban instance bans an IP, it executes the custom action which sends a POST request to the callback URL (`/api/ban` endpoint)
+- When a Fail2Ban instance bans an IP, it executes the custom action which sends a POST request including the secret to the callback URL (`/api/ban` endpoint)
-- Fail2Ban UI receives these notifications and stores them in the database for monitoring and analysis
+- If the secret is missing or wrong the request is dropped.
+- If the secret is valid, Fail2Ban-UI receives these notifications and stores them in the database for monitoring and analysis
 - The callback URL is automatically synchronized with the server port when using the default localhost pattern
 
 **Configuration Guidelines:**
@@ -417,21 +472,16 @@ The **Fail2Ban Callback URL** is a critical setting that determines how Fail2Ban
 - If using a reverse proxy, configure it to forward `/api/ban` requests to Fail2Ban UI
 - The callback URL is stored in `/etc/fail2ban/action.d/ui-custom-action.conf` on each managed Fail2Ban instance
 
-#### Adding a Local Server
+#### Adding a Local Server after initial setup
 
 The local connector allows managing Fail2Ban on the same host where Fail2Ban UI runs.
 
-**Requirements:**
-- Fail2Ban installed and running
-- Special FACL Rules and passwordless sudo to `/usr/bin/fail2ban-client`
-- Socket access: `/var/run/fail2ban/fail2ban.sock`
-
 **Enable in UI:**
 1. Navigate to **Settings** → **Manage Servers**
 2. Enable **Local Connector**
 3. Test connection to verify access
 
-#### Adding an SSH Server
+#### Adding an SSH Server after initial setup
 
 Connect to remote Fail2Ban instances via SSH for centralized management.
 
@@ -469,18 +519,13 @@ sudo setfacl -dRm u:sa_fail2ban:rwX /etc/fail2ban
 3. Select **SSH** connection type
 4. Configure:
    - **Name**: Descriptive server identifier
-   - **Host**: IP address or hostname
+   - **Host**: IP address or hostname (ip is always better, if DNS fails for some reason)
    - **Port**: SSH port (default: 22)
    - **SSH User**: Service account username
    - **SSH Key**: Select from `~/.ssh/` directory
-5. Click **Test Connection** to verify
+5. Tick "Enable connector"
 6. Save configuration
-
+7. Click **Test Connection** to verify
-**Security Benefits:**
-- Least privilege access model
-- No full sudo access required
-- Fine-grained file system permissions
-- Audit trail via sudo logs
 
 ---
 
@@ -494,9 +539,10 @@ sudo setfacl -dRm u:sa_fail2ban:rwX /etc/fail2ban
 
 #### Authentication and Authorization
 
-- **SSH Key Management**: Use strong SSH keys like 4096-bit RSA or even better Ed25519. When using RSA no smaler bit size please.
+- **SSH Key Management**: Use strong SSH keys like 4096-bit RSA or even better Ed25519. When using RSA no smaller bit size please.
 - **Service Accounts**: Use dedicated service accounts, not personal accounts
 - **Sudoers Configuration**: Minimal sudo permissions, no passwordless full sudo
+- **Callback Secret**: Auto-generated secret authenticates all ban notification requests; keep it secure and never expose
 
 #### Data Protection
 
@@ -610,6 +656,9 @@ Fail2Ban UI provides a RESTful API for programmatic access:
 
 **Notifications:**
 - `POST /api/ban` - Receive ban notification from Fail2Ban
+  - **Authentication**: Requires `X-Callback-Secret` header with valid secret
+  - **Request Body**: JSON with `serverId`, `ip`, `jail`, `hostname`, `failures`, `logs`
+  - **Response**: 200 OK on success, 401 Unauthorized if secret is invalid
 
 ---
 

deployment/container/README.md

@@ -35,7 +35,6 @@ podman run -d \
   -v /etc/fail2ban:/etc/fail2ban:Z \
   -v /var/log:/var/log:ro \
   -v /var/run/fail2ban:/var/run/fail2ban \
-  -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
   registry.swissmakers.ch/infra/fail2ban-ui:latest
 ```
 
@@ -61,10 +60,10 @@ Access the web interface at `http://localhost:8080` (or your configured port).
 2. **Build the image:**
    ```bash
    # Using Podman
-   podman build -t fail2ban-ui:latest .
+   podman build -t fail2ban-ui:dev .
    
    # Using Docker
-   docker build -t fail2ban-ui:latest .
+   docker build -t fail2ban-ui:dev .
    ```
 
    > **Note:** The Dockerfile uses a multi-stage build with two stages: `builder` (compiles the Go binary) and `standalone-ui` (final runtime image).
@@ -85,14 +84,14 @@ You can customize the build with additional flags:
 podman build -t fail2ban-ui:v1.0.0 .
 
 # Build without cache
-podman build --no-cache -t fail2ban-ui:latest .
+podman build --no-cache -t fail2ban-ui:dev .
 ```
 
 ---
 
 ## Running the Container
 
-### Basic Run Command
+### Basic Run Command (for a local fail2ban connection)
 
 ```bash
 podman run -d \
@@ -102,7 +101,6 @@ podman run -d \
   -v /etc/fail2ban:/etc/fail2ban:Z \
   -v /var/log:/var/log:ro \
   -v /var/run/fail2ban:/var/run/fail2ban \
-  -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
   fail2ban-ui:latest
 ```
 
@@ -119,7 +117,6 @@ podman run -d \
   -v /etc/fail2ban:/etc/fail2ban:Z \
   -v /var/log:/var/log:ro \
   -v /var/run/fail2ban:/var/run/fail2ban \
-  -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
   fail2ban-ui:latest
 ```
 
@@ -172,7 +169,7 @@ The Fail2Ban UI container requires several volume mounts to function properly. B
   - `.ssh/` - Directory for SSH keys used for remote server connections
   - Application configuration files
 
-#### `/etc/fail2ban` - Fail2Ban Configuration Directory
+#### `/etc/fail2ban` - Fail2Ban Configuration Directory (reqired for local fail2ban connector only)
 - **Host Path:** `/etc/fail2ban`
 - **Container Path:** `/etc/fail2ban`
 - **Purpose:** Access to Fail2Ban configuration files (jails, filters, actions)
@@ -180,7 +177,7 @@ The Fail2Ban UI container requires several volume mounts to function properly. B
 - **SELinux Context:** `:Z` flag required on SELinux-enabled systems
 - **Note:** Required if managing local Fail2Ban instance
 
-#### `/var/run/fail2ban` - Fail2Ban Socket Directory
+#### `/var/run/fail2ban` - Fail2Ban Socket Directory (reqired for local fail2ban connector only)
 - **Host Path:** `/var/run/fail2ban`
 - **Container Path:** `/var/run/fail2ban`
 - **Purpose:** Access to Fail2Ban control socket (`fail2ban.sock`)
@@ -188,23 +185,21 @@ The Fail2Ban UI container requires several volume mounts to function properly. B
 - **SELinux Context:** Not required (tmpfs)
 - **Note:** Required for local Fail2Ban management
 
-### Optional Volumes
+#### `/var/log` - Log Files (reqired for local fail2ban connector only)
-
-#### `/var/log` - System Log Files
 - **Host Path:** `/var/log`
 - **Container Path:** `/var/log`
-- **Purpose:** Read access to system logs for filter testing and log analysis
+- **Purpose:** Read access to system logs for automatically logpath-tests on jail enabe
 - **Permissions:** Read-Only (`:ro`)
-- **SELinux Context:** `:ro` flag prevents SELinux issues
+- **Note:** If test fails, jail is auto-disabled to prevent fail2ban daemon errors
-- **Note:** Useful for testing Fail2Ban filters against log files
 
-#### `/usr/share/GeoIP` - GeoIP Database Directory
+### Optional Volumes
-- **Host Path:** `/usr/share/GeoIP`
+
-- **Container Path:** `/usr/share/GeoIP`
+#### GeoLite2-Country.mmdb - GeoIP Database
-- **Purpose:** Access to GeoIP databases for geographic threat analysis
+- **Host Path:** `/path/to/your/GeoIPFolder`
+- **Container Path:** e.g. `/usr/share/GeoIP` paht must match the settings in the UI.
+- **Purpose:** Only needed if you want to use the MaxMind provider.
 - **Permissions:** Read-Only (`:ro`)
-- **SELinux Context:** `:ro` flag prevents SELinux issues
+- **Note:** Fail2Ban UI uses the built-in ip-api.com by default, which requires no local database
-- **Note:** Optional but recommended for geographic IP analysis features
 
 ### Volume Summary Table
 
@@ -213,8 +208,8 @@ The Fail2Ban UI container requires several volume mounts to function properly. B
 | `/config` | ✅ Yes | Read/Write | `:Z` | Database, settings, SSH keys |
 | `/etc/fail2ban` | ✅ Yes* | Read/Write | `:Z` | Fail2Ban configuration files |
 | `/var/run/fail2ban` | ✅ Yes* | Read/Write | - | Fail2Ban control socket |
-| `/var/log` | ⚠️ Optional | Read-Only | `:ro` | System log files |
+| `/var/log` | ✅ Yes* | Read-Only | `:ro` | System log files for automated logpath tests on jail management. |
-| `/usr/share/GeoIP` | ⚠️ Optional | Read-Only | `:ro` | GeoIP databases |
+| `/path/to/your/GeoIPFolder` | ⚠️ Optional | Read-Only | `:ro` | MaxMind GeoIP databases (only needed if using MaxMind provider) |
 
 *Required only if managing a local Fail2Ban instance. Not needed for remote-only deployments.
 
@@ -246,6 +241,9 @@ After starting the container, access the web interface and configure your first
      - For local deployments: Use the same port as Fail2Ban UI (e.g., `http://127.0.0.1:8080` or your configured port)
      - For reverse proxy setups: Use your TLS-encrypted endpoint (e.g., `https://fail2ban.example.com`)
      - The callback URL automatically updates when you change the server port (if using the default localhost pattern)
+   - **Callback URL Secret**: Auto-generated 42-character secret for authenticating ban notification requests (viewable in Settings with show/hide toggle)
+   - **GeoIP Provider**: Choose between MaxMind (local database) or Built-in (ip-api.com) - default is Built-in
+   - **Maximum Log Lines**: Configure how many log lines to include in ban notifications (default: 50)
    - Set up email alerts (optional)
    - Configure language preferences
    - Adjust security settings
@@ -261,31 +259,40 @@ After starting the container, access the web interface and configure your first
 For easier management, you can use Docker Compose. Create a `docker-compose.yml` file:
 
 ```yaml
-version: '3.8'
-
 services:
   fail2ban-ui:
+    # Use pre-built image from registry
     image: registry.swissmakers.ch/infra/fail2ban-ui:latest
-    # Or build from source:
+
+    # Or build from source (uncomment to use):
     # build:
     #   context: .
     #   dockerfile: Dockerfile
+
     container_name: fail2ban-ui
+    #privileged: true # needed if you want to use a container-local fail2ban instance (because fail2ban.sock is owned by root)
+    # a single all-in-one container is planned, currently you need to use the fail2ban container from linuxserver, see docker-compose-allinone.yml for an example
     network_mode: host
-    restart: unless-stopped
+
     environment:
-      - PORT=8436  # Custom port (optional, defaults to 8080)
+      # Change this to use a different port for the web interface (defaults is 8080)
+      - PORT=8080
+
     volumes:
-      # Required: Configuration and database storage
+      # Required for fail2ban-ui: Stores SQLite database, application settings, and SSH keys of the fail2ban-ui container
       - /opt/podman-fail2ban-ui:/config:Z
-      # Required: Fail2Ban configuration directory
+      # Required for fail2ban-ui: Used for testing, that logpath is working, before enabeling a jail. Without this read only access the fail2ban-ui will not be able to enable jails (logpath-test would fail)
-      - /etc/fail2ban:/etc/fail2ban:Z
-      # Required: Fail2Ban socket directory
-      - /var/run/fail2ban:/var/run/fail2ban
-      # Optional: System logs (read-only)
       - /var/log:/var/log:ro
-      # Optional: GeoIP databases (read-only)
+
-      - /usr/share/GeoIP:/usr/share/GeoIP:ro
+      # Required for local fail2ban instance: Fail2Ban configuration directory, needed for managing a local Fail2Ban instance (e.g. on host system) via fail2ban-ui
+      - /etc/fail2ban:/etc/fail2ban:Z
+      # Required for local fail2ban instance: Fail2Ban socket directory, needed for local Fail2Ban (e.g. on host system) for control via fail2ban-ui
+      - /var/run/fail2ban:/var/run/fail2ban
+
+      # Optional: Map MaxMind GeoIP databases (only needed if using MaxMind provider)
+      #- /usr/share/GeoIP:/usr/share/GeoIP:ro
+
+    restart: unless-stopped
 ```
 
 **Start with Docker Compose:**
@@ -303,6 +310,44 @@ docker-compose logs -f
 docker-compose down
 ```
 
+### All-in-One Docker Compose Setup
+
+For a complete containerized setup with both Fail2Ban and Fail2Ban UI, use the all-in-one Docker Compose configuration:
+
+```bash
+# Copy the all-in-one example file
+cp ../docker-compose-allinone.example.yml docker-compose.yml
+
+# Edit docker-compose.yml to customize:
+# - PORT environment variable for Fail2Ban UI
+# - Timezone (TZ environment variable)
+# - Volume paths
+
+# Start both services
+docker-compose up -d
+```
+
+**Features:**
+- **Combined Setup**: Fail2Ban (linuxserver/fail2ban) and Fail2Ban UI in one compose file
+- **Shared Configuration**: Both containers share the same Fail2Ban configuration directory
+- **Shared Socket**: Both containers access the same Fail2Ban control socket
+- **Network Mode**: Uses `host` network mode for proper iptables integration
+
+**Volume Structure:**
+```
+./fail2ban-config/fail2ban  → /config/fail2ban (fail2ban container)
+./fail2ban-config/fail2ban  → /etc/fail2ban (fail2ban-ui container)
+./f2b-run                   → /var/run/fail2ban (both containers)
+./config                    → /config (fail2ban-ui container)
+```
+
+**Important Notes:**
+- The fail2ban-ui container requires `privileged: true` to modify Fail2Ban configs owned by root
+- Both containers must use `network_mode: host` for proper networking
+- Ensure SELinux labels are correct (`:z` or `:Z` flags)
+
+See `docker-compose-allinone.example.yml` in the project root for the complete configuration.
+
 ---
 
 ## SELinux Configuration

deployment/systemd/README.md

@@ -16,11 +16,15 @@ semodule -i fail2ban-curl-allow.pp
 In this case we will run **Fail2Ban-UI from `/opt/fail2ban-ui/`** using systemd.
 
 ### Prerequisites
-Install **Go 1.22+** and required dependencies:
+Install **Go 1.24+** and required dependencies:
   ```bash
-  sudo dnf install -y golang git whois
+  sudo dnf install -y golang git
   ```
-Make sure you setup GeoIP and your country database is available under: `/usr/share/GeoIP/GeoLite2-Country.mmdb`
+> **Note:** Whois lookups are now performed by Fail2Ban UI directly (no Linux `whois` binary required).
+
+> **Note:** GeoIP lookups can use either:
+> - **Built-in (ip-api.com)**: Default option, requires no installation
+> - **MaxMind (Local Database)**: Optional, requires MaxMind GeoIP database at `/usr/share/GeoIP/GeoLite2-Country.mmdb`
 
 > **Note:** The local Fail2ban service is optional. Fail2Ban-UI can manage remote Fail2ban servers via SSH or API agents without requiring a local Fail2ban installation.
 
@@ -33,6 +37,7 @@ Clone the repository to `/opt/fail2ban-ui`:
 
 ### Create the fail2ban-ui.service
 Save this file as `/etc/systemd/system/fail2ban-ui.service`:
+For production deployments, please use a dedicated service account instead of root.
 
 ```ini
 [Unit]
@@ -87,10 +92,18 @@ After starting the service, access the web interface at `http://localhost:8080`
 
 **Important:** On first launch, you need to:
 1. **Enable the local connector** (if Fail2ban runs on the same host), OR
-2. **Add a remote server** via SSH or API agent
+2. **Add a remote server** via SSH connection
 
 Go to **Settings** → **Manage Servers** in the web UI to configure your first Fail2ban server.
 
+**Configure Settings:**
+- **Fail2Ban Callback URL**: URL where Fail2Ban instances send ban alerts (auto-updates with port changes)
+- **Callback URL Secret**: Auto-generated 42-character secret for API authentication (viewable in Settings with show/hide toggle)
+- **GeoIP Provider**: Choose between MaxMind (local database) or Built-in (ip-api.com)
+- **Maximum Log Lines**: Configure how many log lines to include in ban notifications (default: 50)
+- Set up email alerts and set alert countries
+- Configure language preferences
+
 The UI uses an embedded SQLite database (`fail2ban-ui.db`) to store all server configurations and ban events. This database is automatically created in the working directory.
 
 ## Running Fail2Ban-UI as a (Systemd controlled) Container
@@ -110,7 +123,6 @@ For **Docker** (if preferred):
 sudo dnf install -y docker
 sudo systemctl enable --now docker
 ```
-Make sure you setup GeoIP and your country database is available under: `/usr/share/GeoIP/GeoLite2-Country.mmdb`
 
 Create the needed folder to store the fail2ban-ui config:
 ```bash
@@ -134,8 +146,7 @@ ExecStart=/usr/bin/podman run --rm \
     -v /etc/fail2ban:/etc/fail2ban:Z \
     -v /var/log:/var/log:ro \
     -v /var/run/fail2ban:/var/run/fail2ban \
-    -v /usr/share/GeoIP:/usr/share/GeoIP:ro \
+    registry.swissmakers.ch/infra/fail2ban-ui:latest
-    localhost/fail2ban-ui
 Restart=always
 RestartSec=10s