https://github.com/victor1234/opds-server

Self-hosted OPDS 1.2 server for browsing a Calibre database
https://github.com/victor1234/opds-server

amd64 arm64 calibre docker ebook opds self-hosted

Last synced: about 1 month ago
JSON representation

Self-hosted OPDS 1.2 server for browsing a Calibre database

• Host: GitHub
• URL: https://github.com/victor1234/opds-server
• Owner: victor1234
• License: mit
• Created: 2025-08-17T22:09:12.000Z (about 2 months ago)
• Default Branch: master
• Last Pushed: 2025-08-27T16:03:20.000Z (about 2 months ago)
• Last Synced: 2025-08-28T00:14:48.042Z (about 2 months ago)
• Topics: amd64, arm64, calibre, docker, ebook, opds, self-hosted
• Language: Python
• Homepage:
• Size: 146 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# OPDS Server

[![CI](https://github.com/victor1234/opds-server/actions/workflows/ci.yml/badge.svg)](https://github.com/victor1234/opds-server/actions/workflows/ci.yml)

[![Docker Image](https://img.shields.io/badge/docker-ghcr.io-blue)](https://ghcr.io/victor1234/opds-server)

📚 Minimal OPDS 1.2 server for browsing a Calibre database.

## Features

- OPDS v1.2 compliant feeds (navigation, acquisition, search)

- Browse by newest, title, or author

- Prebuilt multi-arch Docker images for `amd64` and `arm64`

- Read-only access to Calibre database

## Service Endpoints

- `/healthz` → *liveness probe* (returns `200` if the server process is alive)

- `/ready` → *readiness probe* (returns `200` if the Calibre database is available)

## Configuration

The server can be configured using environment variables

| Variable               | Default  | Description                                      |

|------------------------|----------|--------------------------------------------------|

| `PAGE_SIZE`            | `30`     | Number of items (books, authors) shown per page in OPDS feeds. |

## Installation / Run

### Docker

```bash

docker run --rm -p 9000:8000 \

  -v /path_to_calibre_directory:/app/calibre:ro \

  ghcr.io/victor1234/opds-server:0.1.1

```

### Docker Compose

```yaml

services:

  opds:

    image: ghcr.io/victor1234/opds-server:0.1.1

    ports:

      - "9000:8000"

    volumes:

      - /path_to_calibre_directory:/app/calibre:ro

```

Then open http://localhost:9000/opds in your OPDS-compatible reader.