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 (version 3.0 or higher) or 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:

./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

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

Creating the Logs Directory

mkdir -p ./logs

Running the Container

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

podman ps

Accessing the Application

Open your browser to:

http://localhost:8000

Manual Setup with Docker

Building the Container

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

Creating the Logs Directory

mkdir -p ./logs

Running the Container

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

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:

podman logs vpn-session-viewer

Docker:

docker logs vpn-session-viewer

Restart the Application

Podman:

podman restart vpn-session-viewer

Docker:

docker restart vpn-session-viewer

Stop the Application

Podman:

podman stop vpn-session-viewer

Docker:

docker stop vpn-session-viewer

Remove the Container

Podman:

podman rm vpn-session-viewer

Docker:

docker rm vpn-session-viewer

Troubleshooting

Check Container Status

Podman:

podman ps -a

Docker:

docker ps -a

Inspect the Container

Podman:

podman inspect vpn-session-viewer

Docker:

docker inspect vpn-session-viewer

Access Container Shell

Podman:

podman exec -it vpn-session-viewer bash

Docker:

docker exec -it vpn-session-viewer bash

Check Files in Container

To verify logs are correctly mounted:

Podman:

podman exec -it vpn-session-viewer ls -la /home/appuser/app/logs

Docker:

docker exec -it vpn-session-viewer ls -la /home/appuser/app/logs