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](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
```