fresh start

CONTAINER_INSTRUCTIONS.md

@@ -0,0 +1,261 @@
+# Container Instructions for FastAPI Domains Application
+
+This guide explains how to run the FastAPI Domains application in a secure rootless container with persistent data 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. **Read-only filesystem**: The container's filesystem is mounted read-only
+3. **Dropped capabilities**: All Linux capabilities are dropped
+4. **No privilege escalation**: The container cannot gain additional privileges
+5. **Minimal base image**: Uses a slim Python image to reduce attack surface
+6. **Non-privileged ports**: Uses port 8000 instead of privileged ports (<1024)
+7. **Persistent volume**: Data is stored in a volume for persistence
+
+## Quick Start with Podman
+
+### Building the Container
+
+```bash
+podman build -t fastapi-domains:latest .
+```
+
+### Creating a Volume
+
+```bash
+podman volume create domain-data
+```
+
+### Running the Container
+
+```bash
+podman run --name fastapi-domains \
+  -p 8000:8000 \
+  -v domain-data:/home/appuser/app/data:Z \
+  -e DB_DIR=/home/appuser/app/data \
+  --security-opt no-new-privileges:true \
+  --read-only \
+  --tmpfs /tmp \
+  --cap-drop ALL \
+  --user 1000:1000 \
+  -d fastapi-domains:latest
+```
+
+### Checking Container Status
+
+```bash
+podman ps
+```
+
+### Accessing the Application
+
+Open your browser to:
+```
+http://localhost:8000
+```
+
+## Quick Start with Docker
+
+### Building the Container
+
+```bash
+docker build -t fastapi-domains:latest .
+```
+
+### Creating a Volume
+
+```bash
+docker volume create domain-data
+```
+
+### Running the Container
+
+```bash
+docker run --name fastapi-domains \
+  -p 8000:8000 \
+  -v domain-data:/home/appuser/app/data \
+  -e DB_DIR=/home/appuser/app/data \
+  --security-opt no-new-privileges:true \
+  --read-only \
+  --tmpfs /tmp \
+  --cap-drop ALL \
+  --user 1000:1000 \
+  -d fastapi-domains:latest
+```
+
+### Checking Container Status
+
+```bash
+docker ps
+```
+
+### Accessing the Application
+
+Open your browser to:
+```
+http://localhost:8000
+```
+
+## Persistent Data
+
+The application stores all data in a volume named `domain-data`. This volume persists even when the container is stopped or removed.
+
+To see information about the volume:
+
+**Podman:**
+```bash
+podman volume inspect domain-data
+```
+
+**Docker:**
+```bash
+docker volume inspect domain-data
+```
+
+## Maintenance
+
+### View Logs
+
+**Podman:**
+```bash
+podman logs fastapi-domains
+```
+
+**Docker:**
+```bash
+docker logs fastapi-domains
+```
+
+### Restart the Application
+
+**Podman:**
+```bash
+podman restart fastapi-domains
+```
+
+**Docker:**
+```bash
+docker restart fastapi-domains
+```
+
+### Stop the Application
+
+**Podman:**
+```bash
+podman stop fastapi-domains
+```
+
+**Docker:**
+```bash
+docker stop fastapi-domains
+```
+
+### Remove the Container
+
+**Podman:**
+```bash
+podman rm fastapi-domains
+```
+
+**Docker:**
+```bash
+docker rm fastapi-domains
+```
+
+## Backup and Restore
+
+### Backup the Database
+
+**Podman:**
+```bash
+podman run --rm -v domain-data:/data:Z -v ./:/backup:Z alpine sh -c "cp /data/domains_db.json /backup/domains_backup_$(date +%Y%m%d).json"
+```
+
+**Docker:**
+```bash
+docker run --rm -v domain-data:/data -v $(pwd):/backup alpine sh -c "cp /data/domains_db.json /backup/domains_backup_$(date +%Y%m%d).json"
+```
+
+### Restore from Backup
+
+**Podman:**
+```bash
+podman run --rm -v domain-data:/data:Z -v ./:/backup:Z alpine sh -c "cp /backup/domains_backup_YYYYMMDD.json /data/domains_db.json"
+```
+
+**Docker:**
+```bash
+docker run --rm -v domain-data:/data -v $(pwd):/backup alpine sh -c "cp /backup/domains_backup_YYYYMMDD.json /data/domains_db.json"
+```
+
+## Creating a Systemd Service (Podman Only)
+
+1. Generate a systemd service file:
+
+```bash
+mkdir -p ~/.config/systemd/user
+podman generate systemd --name fastapi-domains --files --new
+```
+
+2. Move the generated file:
+
+```bash
+mv container-fastapi-domains.service ~/.config/systemd/user/
+```
+
+3. Enable and start the service:
+
+```bash
+systemctl --user enable container-fastapi-domains.service
+systemctl --user start container-fastapi-domains.service
+```
+
+4. Check service status:
+
+```bash
+systemctl --user status container-fastapi-domains.service
+```
+
+## Troubleshooting
+
+### Check Container Status
+
+**Podman:**
+```bash
+podman ps -a
+```
+
+**Docker:**
+```bash
+docker ps -a
+```
+
+### Inspect the Container
+
+**Podman:**
+```bash
+podman inspect fastapi-domains
+```
+
+**Docker:**
+```bash
+docker inspect fastapi-domains
+```
+
+### Access Container Shell
+
+**Podman:**
+```bash
+podman exec -it fastapi-domains bash
+```
+
+**Docker:**
+```bash
+docker exec -it fastapi-domains bash
+```