init

CONTAINER_INSTRUCTIONS.md

@@ -0,0 +1,227 @@
+# 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
+```