# Calibre-web

## Overview
The Calibre-web stack is a Docker Swarm configuration for hosting the Calibre-web application in NetGrimoire. The service uses the crocodilestick/calibre-web-automated image, which includes automated setup and upgrade scripts.

---

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|-------|
- **Calibre-web**: crocodilestick/calibre-web-automated:latest | 8083 | Web UI |
- **Caddy Reverse Proxy**: none | Internal only | Load Balancer |

---

## Build & Configuration

### Prerequisites
No specific prerequisites are required for this stack.

### Volume Setup
```bash
mkdir -p /DockerVol/Calibre-web/Config
chown -R user:group /DockerVol/Calibre-web/Config
```

### Environment Variables
```bash
PUID=1964
PGID=1964
TZ=America/Chicago
CWA_PORT_OVERRIDE=8083

# Generate secrets for environment variables
generate: openssl rand -hex 32
```

### Deploy
```bash
cd services/swarm/stack/Calibre-web
set -a && source .env && set +a
docker stack config --compose-file Calibre-web-stack.yml > resolved.yml
docker stack deploy --compose-file resolved.yml Calibre-web
rm resolved.yml
docker stack services Calibre-web

# First Run: Set environment variables for the first time
./deploy.sh
```

---

## User Guide

### Accessing Calibre-web
| Service | URL |
|---------|-----|
- **Calibre-web**: http://calibre-web:8083 |

### Primary Use Cases
The primary use case for this stack is to provide a web interface for managing and accessing the Calibre library.

### NetGrimoire Integrations
This service integrates with other services in NetGrimoire, including Kuma for monitoring and CrowdSec for security. The environment variables CWA_PORT_OVERRIDE and CWA_URL are used to configure these integrations.

---

## Operations

### Monitoring
```bash
docker stack services Calibre-web
docker logs -f Calibre-web
```

### Backups
Critical: All data stored in the /DockerVol/Calibre-web/Config volume should be backed up regularly.

Reconstructable: The container image can be recreated from Docker Hub or a private registry.

---

## Common Failures
| Failure Mode | Symptom | Cause | Fix |
|-------------|----------|-------|------|
| Port not available | Unable to access Calibre-web UI | Incorrect CWA_PORT_OVERRIDE environment variable | Check and correct the environment variable |
| Missing configuration | Calibre-web UI is empty or missing configuration | Missing or incorrect environment variables in .env file | Check and correct the environment variables in .env file |
| Service not running | Calibre-web service is not running | Service not started after deploy | Restart the service with docker stack services Calibre-web |

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-05-01 | c3b0c0f5 | Initial documentation for Calibre-web Stack |
| 2026-04-29 | 11e0a461 | Updated environment variables to include CWA_PORT_OVERRIDE |
| 2026-04-29 | 8e2d4d37 | Added security labels to the service, including CrowdSec and authentik imports |
| 2026-04-29 | 52d09425 | Improved documentation for First Run script |
| 2026-04-29 | d85b5700 | Corrected typo in volume setup instructions |

<Note: This is the initial documentation for the Calibre-web Stack. The Changelog section will be updated as new commits are made to the repository.