Skip to content

README.md

Latest commit

 

History

History
116 lines (86 loc) · 3.97 KB

README.md

File metadata and controls

116 lines (86 loc) · 3.97 KB

ChurchTools API

Test and Build Docker Image Python 3.12+ License

A web application for creating styled announcement slides from ChurchTools calendar events — exported as PDF or JPEG for use in church services.

Startseite

Kalenderauswahl

Folienerstellung

Features

  • Calendar selection — choose one or more public calendars from your ChurchTools instance
  • PDF & JPEG export — generate formatted appointment lists with customizable styling
  • Responsive dashboard — manage calendars, formatting, and exports from a single interface

Quick Start

Docker (recommended)

docker run -d \
  -e CHURCHTOOLS_BASE=your-instance.church.tools \
  -v ./data:/app/data \
  -p 5005:5005 \
  schowave/churchtools:latest

Open http://localhost:5005

From Source

git clone https://github.com/schowave/churchtools-api.git
cd churchtools-api
cp .env.example .env           # set CHURCHTOOLS_BASE
python -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
make run

Configuration

Variable Required Default Description
CHURCHTOOLS_BASE Yes — Your ChurchTools domain (e.g. my-church.church.tools)
DB_PATH No churchtools.db Path to the SQLite database file
TIMEZONE No Europe/Berlin Timezone for date display (any valid IANA timezone)
LOG_FORMAT No console Log output format: console (human-readable) or json

Deployment

Synology NAS

  1. Create a project folder on your NAS (e.g. /volume1/docker/churchtools/)

  2. Add the docker-compose.yml from this repository

  3. Create a .env file with your configuration:

    CHURCHTOOLS_BASE=your-instance.church.tools

  4. In Container Manager → Project → Create, point to the folder and start

The included Watchtower service monitors Docker Hub and automatically updates the container when a new release is published.

Other Platforms

The Docker image schowave/churchtools is built for linux/amd64. It works on any x86_64 platform that supports Docker or Podman.

# docker-compose.yml
services:
  churchtools-api:
    image: schowave/churchtools:latest
    ports:
      - "5005:5005"
    volumes:
      - ./data:/app/data
    environment:
      - CHURCHTOOLS_BASE=your-instance.church.tools
    restart: unless-stopped

Releases

Releases are managed via GitHub Actions:

  1. Go to Actions → Release → Run workflow
  2. Either enter a version number (e.g. 3.1.0) or leave empty to auto-increment the patch version (e.g. 3.0.2 → 3.0.3)
  3. The workflow runs tests, updates pyproject.toml, creates a git tag, builds a multi-arch Docker image, and pushes to Docker Hub
  4. Watchtower picks up the new image automatically on connected hosts

Requires GitHub Secrets: DOCKERHUB_USERNAME and DOCKERHUB_TOKEN

Development

Command Description
make run Run migrations and start dev server with auto-reload
make test Run test suite
make lint Check code style (ruff)
make format Auto-fix code style
make build Build container image locally

CI runs lint and tests on every push to main and on pull requests.