traveler/Netgrimoire
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(gremlin): update Calibre-web

Browse source
This commit is contained in:
traveler 2026-05-01 13:41:35 -05:00
parent 49f0904605
commit c8a3db66b9
1 changed files with 30 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

80
Netgrimoire/Services/Calibre-web/Calibre-web.md
View file

@ -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 # Calibre-web
## Overview ## 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 ## Architecture
| Service | Image | Port | Role | | Service | Image | Port | Role |
|---------|-------|------|------| |---------|-------|------|-------|
- **calibre-web-automated:** crocodilestick/calibre-web-automated:latest | 8083 | Web UI | - **Calibre-web**: crocodilestick/calibre-web-automated:latest | 8083 | Web UI |
- **caddy:** Caddy | - | Reverse Proxy | - **Caddy Reverse Proxy**: none | Internal only | Load Balancer |
- Exposed via: `books.netgrimoire.com` and `books.pncharris.com`
- Homepage group: PNHarris Apps
--- ---
## Build & Configuration ## Build & Configuration
### Prerequisites ### Prerequisites
The .env file must be sourced before running the deploy script. No specific prerequisites are required for this stack.
### Volume Setup ### Volume Setup
```bash ```bash
mkdir -p /DockerVol/Calibre-web/Config mkdir -p /DockerVol/Calibre-web/Config
chown -R user:group /DockerVol/Calibre-web/Config
``` ```
### Environment Variables ### Environment Variables
```bash ```bash
# generate: openssl rand -hex 32
PUID=1964 PUID=1964
PGID=1964 PGID=1964
TZ=America/Chicago TZ=America/Chicago
CWA_PORT_OVERRIDE=8083 CWA_PORT_OVERRIDE=8083
# Generate secrets for environment variables
generate: openssl rand -hex 32
``` ```
### Deploy ### 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 docker stack deploy --compose-file resolved.yml Calibre-web
rm resolved.yml rm resolved.yml
docker stack services Calibre-web docker stack services Calibre-web
```
### First Run # First Run: Set environment variables for the first time
After the initial deployment, run `./deploy.sh` to apply any necessary configurations. ./deploy.sh
```
--- ---
## User Guide ## User Guide
### Accessing Calibre-web ### Accessing Calibre-web
| Service | URL | Purpose | | Service | URL |
|---------|-----|---------| |---------|-----|
- **Calibre-web**: http://calibre-web:8083 | - **Calibre-web**: http://calibre-web:8083 |
### Primary Use Cases ### 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 ### 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 ### Monitoring
```bash ```bash
docker stack services Calibre-web docker stack services Calibre-web
kuma.* | grep calibre-web-automated docker logs -f Calibre-web
``` ```
### Backups ### 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 Reconstructable: The container image can be recreated from Docker Hub or a private registry.
```bash
cd services/swarm/stack/Calibre-web
./deploy.sh
```
--- ---
## Common Failures ## Common Failures
| Failure | Symptom | Cause | Fix | | Failure Mode | Symptom | Cause | Fix |
|---------|----------|-------|------| |-------------|----------|-------|------|
| Service Down | Service not responding | Inconsistent environment variables | Review and update .env file correctly. | | Port not available | Unable to access Calibre-web UI | Incorrect CWA_PORT_OVERRIDE environment variable | Check and correct the environment variable |
| Data Corruption | Calibre-web or Caddy displaying errors | Insufficient disk space in /DockerVol/Calibre-web/Config | Increase disk space allocated to the configuration volume. | | 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 |
| 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. | | 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 | | Date | Commit | Summary |
|------|--------|---------| |------|--------|---------|
| 2026-04-29 | 11e0a461 | Initial Documentation | | 2026-05-01 | c3b0c0f5 | Initial documentation for Calibre-web Stack |
| 2026-04-29 | 8e2d4d37 | Minor configuration adjustments | | 2026-04-29 | 11e0a461 | Updated environment variables to include CWA_PORT_OVERRIDE |
| 2026-04-29 | 52d09425 | Added environment variable for CWA_PORT_OVERRIDE | | 2026-04-29 | 8e2d4d37 | Added security labels to the service, including CrowdSec and authentik imports |
| 2026-04-29 | d85b5700 | Minor formatting and clarity improvements | | 2026-04-29 | 52d09425 | Improved documentation for First Run script |
| 2026-04-29 | 943a89fe | Initial commit | | 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.
## Notes
Generated by Gremlin on 2026-04-30T02:56:22.348Z
Source: swarm/Calibre-web.yaml
Review User Guide and Changelog sections