VPN-Session-History-FastAPI/CONTAINER_INSTRUCTIONS.md

# Container Instructions for VPN Session Viewer

This guide explains how to run the VPN Session Viewer application in a secure rootless container with persistent log storage using Podman or Docker.

## Prerequisites

- [Podman](https://podman.io/getting-started/installation) (version 3.0 or higher) or [Docker](https://docs.docker.com/get-docker/) (version 20.10 or higher)

## Security Features

This deployment includes the following security features:

1. **Rootless container**: The application runs as a non-root user (UID 1000)
2. **Dropped capabilities**: All Linux capabilities are dropped 
3. **No privilege escalation**: The container cannot gain additional privileges
4. **Minimal base image**: Uses a slim Python image to reduce attack surface
5. **Non-privileged ports**: Uses port 8000 instead of privileged ports (<1024)
6. **Persistent volume**: VPN logs are stored in a volume for persistence

## Quick Start with Provided Script

The easiest way to run the container is using the included script:

```bash
./run_container.sh
```

This script will automatically:
1. Detect whether to use Podman or Docker
2. Build the container image
3. Create a logs directory if it doesn't exist
4. Run the container with all necessary security settings

## Manual Setup with Podman

### Building the Container

```bash
podman build -t vpn-session-viewer:latest .
```

### Creating the Logs Directory

```bash
mkdir -p ./logs
```

### Running the Container

```bash
podman run --name vpn-session-viewer \
  -p 8000:8000 \
  -v ./logs:/home/appuser/app/logs:Z \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  --user 1000:1000 \
  -d vpn-session-viewer:latest
```

### Checking Container Status

```bash
podman ps
```

### Accessing the Application

Open your browser to:
```
http://localhost:8000
```

## Manual Setup with Docker

### Building the Container

```bash
docker build -t vpn-session-viewer:latest .
```

### Creating the Logs Directory

```bash
mkdir -p ./logs
```

### Running the Container

```bash
docker run --name vpn-session-viewer \
  -p 8000:8000 \
  -v ./logs:/home/appuser/app/logs \
  --security-opt no-new-privileges:true \
  --cap-drop ALL \
  --user 1000:1000 \
  -d vpn-session-viewer:latest
```

### Checking Container Status

```bash
docker ps
```

### Accessing the Application

Open your browser to:
```
http://localhost:8000
```

## Working with VPN Logs

### Log File Format

Log files should follow this naming convention:
```
{gateway-name}_{ISO-timestamp}.logs
```

Example: `firewall-1_2025-04-10T17:04:51Z.logs`

### Adding Log Files

Simply place your VPN log files in the `./logs` directory on your host machine. The container will automatically access them.

## Maintenance

### View Logs

**Podman:**
```bash
podman logs vpn-session-viewer
```

**Docker:**
```bash
docker logs vpn-session-viewer
```

### Restart the Application

**Podman:**
```bash
podman restart vpn-session-viewer
```

**Docker:**
```bash
docker restart vpn-session-viewer
```

### Stop the Application

**Podman:**
```bash
podman stop vpn-session-viewer
```

**Docker:**
```bash
docker stop vpn-session-viewer
```

### Remove the Container

**Podman:**
```bash
podman rm vpn-session-viewer
```

**Docker:**
```bash
docker rm vpn-session-viewer
```

## Troubleshooting

### Check Container Status

**Podman:**
```bash
podman ps -a
```

**Docker:**
```bash
docker ps -a
```

### Inspect the Container

**Podman:**
```bash
podman inspect vpn-session-viewer
```

**Docker:**
```bash
docker inspect vpn-session-viewer
```

### Access Container Shell

**Podman:**
```bash
podman exec -it vpn-session-viewer bash
```

**Docker:**
```bash
docker exec -it vpn-session-viewer bash
```

### Check Files in Container

To verify logs are correctly mounted:

**Podman:**
```bash
podman exec -it vpn-session-viewer ls -la /home/appuser/app/logs
```

**Docker:**
```bash
docker exec -it vpn-session-viewer ls -la /home/appuser/app/logs
```