domainapi/CONTAINER_INSTRUCTIONS.md

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

podman build -t fastapi-domains:latest .

Creating a Volume

podman volume create domain-data

Running the Container

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

podman ps

Accessing the Application

Open your browser to:

http://localhost:8000

Quick Start with Docker

Building the Container

docker build -t fastapi-domains:latest .

Creating a Volume

docker volume create domain-data

Running the Container

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

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:

podman volume inspect domain-data

Docker:

docker volume inspect domain-data

Maintenance

View Logs

Podman:

podman logs fastapi-domains

Docker:

docker logs fastapi-domains

Restart the Application

Podman:

podman restart fastapi-domains

Docker:

docker restart fastapi-domains

Stop the Application

Podman:

podman stop fastapi-domains

Docker:

docker stop fastapi-domains

Remove the Container

Podman:

podman rm fastapi-domains

Docker:

docker rm fastapi-domains

Backup and Restore

Backup the Database

Podman:

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:

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:

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:

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:

mkdir -p ~/.config/systemd/user
podman generate systemd --name fastapi-domains --files --new

2. Move the generated file:

mv container-fastapi-domains.service ~/.config/systemd/user/

3. Enable and start the service:

systemctl --user enable container-fastapi-domains.service
systemctl --user start container-fastapi-domains.service

4. Check service status:

systemctl --user status container-fastapi-domains.service

Troubleshooting

Check Container Status

Podman:

podman ps -a

Docker:

docker ps -a

Inspect the Container

Podman:

podman inspect fastapi-domains

Docker:

docker inspect fastapi-domains

Access Container Shell

Podman:

podman exec -it fastapi-domains bash

Docker:

docker exec -it fastapi-domains bash