# Calibre-web

## Overview
The Calibre-web stack is a Docker Swarm configuration for the Calibre-web application in NetGrimoire, providing an automated web interface for managing Calibre libraries.

---

## Architecture
| Service | Image | Port | Role |
|---------|-------|------|-----|
- **calibre-web-automated:** crocodilestick/calibre-web-automated:latest | 8083 | Web UI |
- Exposed via: books.netgrimoire.com, books.pncharris.com (Caddy reverse proxy) |
- Homepage group: PNCHarris Apps |

---

## Build & Configuration

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

### Volume Setup
```bash
mkdir -p /DockerVol/Calibre-web/Config:/config
mkdir -p /DockerVol/Calibre-web/Ingest:/cwa-book-ingest
```

### Environment Variables
```bash
# generate: openssl rand -hex 32
PUID=1964
PGID=1964
TZ=America/Chicago
```

### 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
After deployment, log in to the web UI at <base URL> and configure the application according to your needs.

---

## User Guide

### Accessing Calibre-web
| Service | URL | Purpose |
|---------|-----|---------|
- **calibre-web-automated:** http://books.netgrimoire.com (Web UI) |

### Primary Use Cases
The primary use case for this stack is managing Calibre libraries in NetGrimoire.

### NetGrimoire Integrations
This service connects to the Uptime Kuma monitoring system and uses Caddy as a reverse proxy.

---

## Operations

### Monitoring
```bash
docker stack services Calibre-web
docker-compose -f docker-compose.yml logs calibre-web-automated
```

### Backups
Critical data is stored in `/DockerVol/Calibre-web/Config` and non-critical data in `/DockerVol/Calibre-web/Ingest`.

### Restore
```bash
cd services/swarm/stack/Calibre-web
./deploy.sh
```

---

## Common Failures
| Symptom | Cause | Fix |
|---------|-------|-----|
- Service does not start | Incorrect environment variables | Review and correct `.env` file |
- Calibre-web UI is slow | Ingest directory is full | Increase ingest directory size or delete old data |
- Monitoring fails | Kuma configuration is incorrect | Review and correct `kuma.*` labels |

---

## Changelog

| Date | Commit | Summary |
|------|--------|---------|
| 2026-04-29 | 8e2d4d37 | Initial documentation |
| 2026-04-29 | 52d09425 | Updated environment variables |
| 2026-04-29 | d85b5700 | Added logging commands to docker-compose.yml |
| 2026-04-29 | 943a89fe | Fixed ingestion directory size error |
| 2026-03-11 | f0a7ad41 | Updated homepage group label |

<The Calibre-web stack has evolved significantly since its initial documentation, with numerous updates and bug fixes to ensure stability and performance. This documentation reflects the current state of the service, providing a comprehensive guide for users and administrators alike.