fail2ban-ui/deployment/container/README.md

# Fail2Ban UI Container Deployment Guide

A comprehensive guide for building and deploying Fail2Ban UI using containers (Docker/Podman).

## Table of Contents

- [Quick Start](#quick-start)
- [Building the Container Image](#building-the-container-image)
- [Running the Container](#running-the-container)
- [Volume Mounts](#volume-mounts)
- [Configuration](#configuration)
- [Docker Compose](#docker-compose)
- [SELinux Configuration](#selinux-configuration)
- [Troubleshooting](#troubleshooting)

---

## Quick Start

### Using Pre-built Image

**Pull the official image:**
```bash
podman pull registry.swissmakers.ch/infra/fail2ban-ui:latest
# or with Docker:
docker pull registry.swissmakers.ch/infra/fail2ban-ui:latest
```

**Run the container:**
```bash
podman run -d \
  --name fail2ban-ui \
  --network=host \
  -v /opt/podman-fail2ban-ui:/config:Z \
  -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://localhost:8080` (or your configured port).

---

## Building the Container Image

### Prerequisites

- Docker or Podman installed
- Git (to clone the repository)

### Build Steps

1. **Clone the repository:**
   ```bash
   git clone https://github.com/swissmakers/fail2ban-ui.git
   cd fail2ban-ui
   ```

2. **Build the image:**
   ```bash
   # Using Podman
   podman build -t fail2ban-ui:latest .
   
   # Using Docker
   docker build -t fail2ban-ui:latest .
   ```

   > **Note:** The Dockerfile uses a multi-stage build with two stages: `builder` (compiles the Go binary) and `standalone-ui` (final runtime image).

3. **Verify the build:**
   ```bash
   podman images fail2ban-ui
   # or
   docker images fail2ban-ui
   ```

### Build Options

You can customize the build with additional flags:

```bash
# Build with a specific tag
podman build -t fail2ban-ui:v1.0.0 .

# Build without cache
podman build --no-cache -t fail2ban-ui:latest .
```

---

## Running the Container

### Basic Run Command

```bash
podman run -d \
  --name fail2ban-ui \
  --network=host \
  -v /opt/podman-fail2ban-ui:/config:Z \
  -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
```

### Custom Port Configuration

You can change the default port (8080) using the `PORT` environment variable:

```bash
podman run -d \
  --name fail2ban-ui \
  --network=host \
  -e PORT=8436 \
  -v /opt/podman-fail2ban-ui:/config:Z \
  -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
```

Access the web interface at `http://localhost:8436`.

### Container Management

**Start the container:**
```bash
podman start fail2ban-ui
```

**Stop the container:**
```bash
podman stop fail2ban-ui
```

**View logs:**
```bash
podman logs -f fail2ban-ui
```

**Remove the container:**
```bash
podman stop fail2ban-ui
podman rm fail2ban-ui
```

**Execute commands inside the container:**
```bash
podman exec -it fail2ban-ui /bin/bash
```

---

## Volume Mounts

The Fail2Ban UI container requires several volume mounts to function properly. Below is a detailed explanation of each volume:

### Required Volumes

#### `/config` - Configuration and Database Storage
- **Host Path:** `/opt/podman-fail2ban-ui` (or your preferred location)
- **Container Path:** `/config`
- **Purpose:** Stores the SQLite database (`fail2ban-ui.db`), application settings, and SSH keys for remote server connections
- **Permissions:** Read/Write
- **SELinux Context:** `:Z` flag required on SELinux-enabled systems
- **Contents:**
  - `fail2ban-ui.db` - SQLite database with server configurations and ban events
  - `.ssh/` - Directory for SSH keys used for remote server connections
  - Application configuration files

#### `/etc/fail2ban` - Fail2Ban Configuration Directory
- **Host Path:** `/etc/fail2ban`
- **Container Path:** `/etc/fail2ban`
- **Purpose:** Access to Fail2Ban configuration files (jails, filters, actions)
- **Permissions:** Read/Write (required for configuration management)
- **SELinux Context:** `:Z` flag required on SELinux-enabled systems
- **Note:** Required if managing local Fail2Ban instance

#### `/var/run/fail2ban` - Fail2Ban Socket Directory
- **Host Path:** `/var/run/fail2ban`
- **Container Path:** `/var/run/fail2ban`
- **Purpose:** Access to Fail2Ban control socket (`fail2ban.sock`)
- **Permissions:** Read/Write
- **SELinux Context:** Not required (tmpfs)
- **Note:** Required for local Fail2Ban management

### Optional Volumes

#### `/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
- **Permissions:** Read-Only (`:ro`)
- **SELinux Context:** `:ro` flag prevents SELinux issues
- **Note:** Useful for testing Fail2Ban filters against log files

#### `/usr/share/GeoIP` - GeoIP Database Directory
- **Host Path:** `/usr/share/GeoIP`
- **Container Path:** `/usr/share/GeoIP`
- **Purpose:** Access to GeoIP databases for geographic threat analysis
- **Permissions:** Read-Only (`:ro`)
- **SELinux Context:** `:ro` flag prevents SELinux issues
- **Note:** Optional but recommended for geographic IP analysis features

### Volume Summary Table

| Volume | Required | Read/Write | SELinux Context | Purpose |
|--------|----------|------------|-----------------|---------|
| `/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 |
| `/usr/share/GeoIP` | ⚠️ Optional | Read-Only | `:ro` | GeoIP databases |

*Required only if managing a local Fail2Ban instance. Not needed for remote-only deployments.

---

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Port number for the web interface |
| `CONTAINER` | `true` | Automatically set by the container (do not override) |

### First Launch Configuration

After starting the container, access the web interface and configure your first Fail2Ban server:

1. **Access the Web Interface**
   - Navigate to `http://localhost:8080` (or your configured port)

2. **Add Your First Server**
   - Go to **Settings** → **Manage Servers**
   - **Local Server**: Enable the local connector if Fail2Ban runs on the same host
   - **Remote Server**: Add via SSH or API agent connection

3. **Configure Settings**
   - Set up email alerts (optional)
   - Configure language preferences
   - Adjust security settings

> **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 in the container.

---

## Docker Compose

For easier management, you can use Docker Compose. Create a `docker-compose.yml` file:

```yaml
version: '3.8'

services:
  fail2ban-ui:
    image: registry.swissmakers.ch/infra/fail2ban-ui:latest
    # Or build from source:
    # build:
    #   context: .
    #   dockerfile: Dockerfile
    container_name: fail2ban-ui
    network_mode: host
    restart: unless-stopped
    environment:
      - PORT=8436  # Custom port (optional, defaults to 8080)
    volumes:
      # Required: Configuration and database storage
      - /opt/podman-fail2ban-ui:/config:Z
      # Required: Fail2Ban configuration directory
      - /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
```

**Start with Docker Compose:**
```bash
docker-compose up -d
```

**View logs:**
```bash
docker-compose logs -f
```

**Stop:**
```bash
docker-compose down
```

---

## SELinux Configuration

If SELinux is enabled on your system, you must apply the required SELinux policies to allow the container to communicate with Fail2Ban.

### Apply Pre-built Policies

The policies are located in `./SELinux/`:

```bash
cd deployment/container/SELinux
semodule -i fail2ban-container-ui.pp
semodule -i fail2ban-container-client.pp
```

### Manually Compile and Install Policies

If you want to modify or compile the SELinux rules yourself:

```bash
cd deployment/container/SELinux

# Compile the module
checkmodule -M -m -o fail2ban-container-client.mod fail2ban-container-client.te

# Package the module
semodule_package -o fail2ban-container-client.pp -m fail2ban-container-client.mod

# Install the module
semodule -i fail2ban-container-client.pp
```

### Verify SELinux Policies

```bash
semodule -l | grep fail2ban
```

You should see:
- `fail2ban-container-ui`
- `fail2ban-container-client`

---

## Troubleshooting

### UI Not Accessible

**Symptoms:** Cannot access web interface

**Solutions:**
1. **Check if container is running:**
   ```bash
   podman ps | grep fail2ban-ui
   ```

2. **Check container logs:**
   ```bash
   podman logs fail2ban-ui
   ```

3. **Verify port is not blocked by firewall:**
   ```bash
   sudo firewall-cmd --list-ports
   sudo firewall-cmd --add-port=8080/tcp --permanent
   sudo firewall-cmd --reload
   ```

4. **Check if Fail2Ban UI process is running inside container:**
   ```bash
   podman exec -it fail2ban-ui ps aux | grep fail2ban-ui
   ```

5. **Verify port configuration:**
   - Check if `PORT` environment variable is set correctly
   - Check container logs for the actual port being used

### No Servers Configured

**Symptoms:** Empty dashboard, no servers visible

**Solutions:**
1. Navigate to **Settings** → **Manage Servers** in the web UI
2. Enable **Local Connector** (if Fail2Ban runs locally)
3. Add remote server via SSH or API agent
4. Verify server connection status

### SSH Connection Issues

**Symptoms:** Cannot connect to remote server

**Solutions:**
1. **Verify SSH key authentication works from the host:**
   ```bash
   ssh -i /opt/podman-fail2ban-ui/.ssh/your_key user@remote-host
   ```

2. **Ensure SSH user has proper permissions on remote server:**
   - Sudo access for `fail2ban-client` and `systemctl restart fail2ban` (configured via sudoers)
   - File system ACLs on `/etc/fail2ban` for configuration file access
   - See the main README for recommended setup with service account and ACLs

3. **Check SSH keys location:**
   - SSH keys should be placed in `/config/.ssh` directory inside the container
   - Verify key permissions (should be 600)

4. **Enable debug mode:**
   - Go to **Settings** → Enable debug mode for detailed error messages

5. **Verify network connectivity:**
   - The container needs network access to remote SSH servers
   - Check if using `--network=host` or configure proper port mappings

### Permission Denied Errors

**Symptoms:** Permission errors when accessing Fail2Ban files

**Solutions:**
1. **Check SELinux context on volumes:**
   ```bash
   ls -Z /opt/podman-fail2ban-ui
   ls -Z /etc/fail2ban
   ```

2. **Apply correct SELinux context:**
   ```bash
   chcon -Rt container_file_t /opt/podman-fail2ban-ui
   ```

3. **Verify volume mount flags:**
   - Use `:Z` flag for read/write volumes on SELinux systems
   - Use `:ro` flag for read-only volumes

### Database Errors

**Symptoms:** Database-related errors in logs

**Solutions:**
1. **Check database file permissions:**
   ```bash
   ls -la /opt/podman-fail2ban-ui/fail2ban-ui.db
   ```

2. **Verify database integrity:**
   ```bash
   podman exec -it fail2ban-ui sqlite3 /config/fail2ban-ui.db "PRAGMA integrity_check;"
   ```

3. **Backup and recreate if corrupted:**
   ```bash
   cp /opt/podman-fail2ban-ui/fail2ban-ui.db /opt/podman-fail2ban-ui/fail2ban-ui.db.backup
   ```

---

## Contact & Support

For issues, contributions, or feature requests, visit our GitHub repository:  
🔗 [GitHub Issues](https://github.com/swissmakers/fail2ban-ui/issues)

For enterprise support, visit:  
🔗 [Swissmakers GmbH](https://swissmakers.ch)