docs(gremlin): update Calibre-web
This commit is contained in:
parent
49f0904605
commit
c8a3db66b9
1 changed files with 30 additions and 50 deletions
|
|
@ -1,49 +1,38 @@
|
|||
---
|
||||
title: Calibre-web Stack
|
||||
description: Automated Calibre-web setup for NetGrimoire
|
||||
published: true
|
||||
date: 2026-04-30T02:56:22.348Z
|
||||
tags: docker,swarm,Calibre-web,netgrimoire
|
||||
editor: markdown
|
||||
dateCreated: 2026-04-30T02:56:22.348Z
|
||||
|
||||
---
|
||||
|
||||
# Calibre-web
|
||||
|
||||
## Overview
|
||||
This stack provides a fully automated setup for Calibre-web in NetGrimoire, utilizing Docker Swarm to manage the service. The main services used are calibre-web-automated and caddy.
|
||||
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-automated:** crocodilestick/calibre-web-automated:latest | 8083 | Web UI |
|
||||
- **caddy:** Caddy | - | Reverse Proxy |
|
||||
|
||||
- Exposed via: `books.netgrimoire.com` and `books.pncharris.com`
|
||||
- Homepage group: PNHarris Apps
|
||||
|---------|-------|------|-------|
|
||||
- **Calibre-web**: crocodilestick/calibre-web-automated:latest | 8083 | Web UI |
|
||||
- **Caddy Reverse Proxy**: none | Internal only | Load Balancer |
|
||||
|
||||
---
|
||||
|
||||
## Build & Configuration
|
||||
|
||||
### Prerequisites
|
||||
The .env file must be sourced before running the deploy script.
|
||||
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
|
||||
# generate: openssl rand -hex 32
|
||||
PUID=1964
|
||||
PGID=1964
|
||||
TZ=America/Chicago
|
||||
CWA_PORT_OVERRIDE=8083
|
||||
|
||||
# Generate secrets for environment variables
|
||||
generate: openssl rand -hex 32
|
||||
```
|
||||
|
||||
### Deploy
|
||||
|
|
@ -54,25 +43,25 @@ 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 the initial deployment, run `./deploy.sh` to apply any necessary configurations.
|
||||
# First Run: Set environment variables for the first time
|
||||
./deploy.sh
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Guide
|
||||
|
||||
### Accessing Calibre-web
|
||||
| Service | URL | Purpose |
|
||||
|---------|-----|---------|
|
||||
| Service | URL |
|
||||
|---------|-----|
|
||||
- **Calibre-web**: http://calibre-web:8083 |
|
||||
|
||||
### Primary Use Cases
|
||||
This service is intended for automated use in NetGrimoire.
|
||||
The primary use case for this stack is to provide a web interface for managing and accessing the Calibre library.
|
||||
|
||||
### NetGrimoire Integrations
|
||||
This service connects to other services via the environment variables specified, including Uptime Kuma and Caddy.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -81,26 +70,22 @@ This service connects to other services via the environment variables specified,
|
|||
### Monitoring
|
||||
```bash
|
||||
docker stack services Calibre-web
|
||||
kuma.* | grep calibre-web-automated
|
||||
docker logs -f Calibre-web
|
||||
```
|
||||
|
||||
### Backups
|
||||
The `/DockerVol/Calibre-web/Config` volume should be backed up regularly to prevent data loss. Critical configurations stored in this directory are marked as such.
|
||||
Critical: All data stored in the /DockerVol/Calibre-web/Config volume should be backed up regularly.
|
||||
|
||||
### Restore
|
||||
```bash
|
||||
cd services/swarm/stack/Calibre-web
|
||||
./deploy.sh
|
||||
```
|
||||
Reconstructable: The container image can be recreated from Docker Hub or a private registry.
|
||||
|
||||
---
|
||||
|
||||
## Common Failures
|
||||
| Failure | Symptom | Cause | Fix |
|
||||
|---------|----------|-------|------|
|
||||
| Service Down | Service not responding | Inconsistent environment variables | Review and update .env file correctly. |
|
||||
| Data Corruption | Calibre-web or Caddy displaying errors | Insufficient disk space in /DockerVol/Calibre-web/Config | Increase disk space allocated to the configuration volume. |
|
||||
| Inability to Access | Unable to reach calibre-web web UI | Configuration issues with caddy | Check for and correct any misconfigured labels, reverse proxy settings, or .env files. |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -108,15 +93,10 @@ cd services/swarm/stack/Calibre-web
|
|||
|
||||
| Date | Commit | Summary |
|
||||
|------|--------|---------|
|
||||
| 2026-04-29 | 11e0a461 | Initial Documentation |
|
||||
| 2026-04-29 | 8e2d4d37 | Minor configuration adjustments |
|
||||
| 2026-04-29 | 52d09425 | Added environment variable for CWA_PORT_OVERRIDE |
|
||||
| 2026-04-29 | d85b5700 | Minor formatting and clarity improvements |
|
||||
| 2026-04-29 | 943a89fe | Initial commit |
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
Generated by Gremlin on 2026-04-30T02:56:22.348Z
|
||||
Source: swarm/Calibre-web.yaml
|
||||
Review User Guide and Changelog sections
|
||||
<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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue