Birthday Calendar Service :: BCS

• Preface
• Disclaimer
• Backend Tests
• Basic Workflow
  • General Steps
• Setup & Configuration
  • File Structure
  • Configuration
• Start
  • by Docker
  • by Docker Compose
  • by Command Line
  • by systemd Service
  • by init.d Service

Give it a try!

Preface

BirthdayCalendarService (BCS): A Java Spring Boot application that creates and synchronizes a birthday calendar from CardDAV address book data. BCS automatically generates recurring birthday events and maintains them through scheduled synchronization with CalDAV servers like SOGO and Baikal. Supports deployment via command line, systemd, init.d, or Docker containers.

Features:

• CardDAV/CalDAV integration

• Intelligent event synchronization

• Automated scheduling with cron

• Docker support

• Java 17+ compatible

• Spring Boot 4.x

• Successfully tested with SOGo, Baikal, Radicale
  see below "Backend Tests"

If you find a bug or certain features are missing, don’t hesitate to file an issue on Github.

Disclaimer

I’m not responsible for any data loss, hardware damage or broken keyboards. This guide comes without any warranty!

Backend Tests

All backend tests:

Single backend tests:

• 

• 

• 

Basic Workflow

The Birthday Calendar Service (BCS) is an application designed to generate a birthday calendar from the contact information stored in a CardDAV address book and upload it to a CalDAV calendar. The working process is built upon key parts and is automated using scheduling methods.

General Steps

1. Address Book Access

   • The application fetches all contacts from the specified address book URL and processes each contact to extract relevant information, such as names and birthdays.

2. Event Processing

   • The collected birthday data is processed to create calendar events. Each contact’s birthday is transformed into a recurring event that adheres to the iCalendar format.

   • A calendar "category" is defined to tag birthdays uniquely, allowing the application to manage these events effectively.

3. Remote Calendar Management

   • The application interacts with the configured CalDAV server and synchronizes the events in the specified birthday calendar. It matches and updates calendar entries to reflect any changes, ensuring that no duplicates or outdated events remain.

4. Automation and Scheduling

   • The entire workflow is automated using a scheduled method, which is triggered periodically based on a cron expression defined in the application configuration. This ensures the calendar stays up-to-date without manual intervention.

Setup & Configuration

File Structure

Here is the suggested file structure:

├── /opt/bcs
│   ├── bcs.yml    (individual configuration)
│   ├── bcs.jar
│   ├── logback.xml    (logback configuration)

bcs.yml defines the individual properties. The file is read by default and will be merged with the default properties in the classpath, therefore, the file can be kept as small as possible. A minimal configuration example can be found further below. If the file is inside the working directory, it is loaded automatically.
The complete configuration settings can be found here.

Configuration

Use the individual properties file bcs.yml to set e.g., the mandatory dav settings and to override default settings.

The most important settings are:

bcs:
  calendar-category: Birthday  # default
  cron: "0 30 4 * * *"  # default
dav:
  user: dev
  password: strong
  cal-url: https://dav.my-domain.org/SOGo/dav/dav-user/Calendar/46-12345678-5-87654321/
  card-url: https://dav.my-domain.org/SOGo/dav/dav-user/Contacts/personal/

• bcs.calendar-category: The value depends on the categories of the caldav server and its localization.
  This value is used to delete and create birthday events, the value must be set correctly initially and must not be changed!

• bcs.run-on-start: Optional parameter, default is false. If it true, the sync starts immediately on start.

• bcs.cron: The cron trigger used to schedule the synchronization of birthdays.

• dav.user, dav.password: Authentication credentials for the dav server.

• dav.card-url: The address book URL from which birthdays are read.

• dav.cal-url: The url of the birthday calendar which must be created. To be on the safe side, it’s a good idea to use an extra birthday calendar! But it is not mandatory since A remote event should only be deleted if its categories contain the defined birthday category. was implemented.

• dav.delay-in-seconds: This property determines the delay interval (in seconds) between retries in the case of network problems. The default setting is 1.

• dav.retry-delay-in-seconds: The maximum number of retries due to network errors. The default setting is 5.

There are additional settings for the birthday event. For further information have a look at the Complete BCS Configuration.

Start

The fully executable jar can be executed in different ways.

by Docker

BCS can be run directly from a container image hosted on GitHub Container Registry (GHCR).

# Run with configuration file mounted from the host
docker run --rm \
  -v /path/to/bcs.yml:/app/bcs.yml:ro \
  -v /path/to/logback.xml:/app/logback.xml:ro \
  ghcr.io/th-schwarz/birthday-calendar-service:[tagged-version]

Replace /path/to/bcs.yml and /path/to/logback.xml with the absolute paths to your configuration and logging files on the host system.

Allowed values for tagged-version:

• latest is built from the main branch.

• develop is built from the develop branch.

• v0.2.0 is built from the tag v0.2.0.

• feature-xyz is built from feature/xyz branch.

If you want the application to run once and exit, you can append:

docker run --rm \
  -v /path/to/bcs.yml:/app/bcs.yml:ro \
  -v /path/to/logback.xml:/app/logback.xml:ro \
  ghcr.io/th-schwarz/birthday-calendar-service:latest --run-once

by Docker Compose

You can also run BCS with Docker Compose for easier service management.

services:
  bcs:
    image: ghcr.io/th-schwarz/birthday-calendar-service:latest   # replace with ghcr.io/th-schwarz/birthday-calendar-service:<tag-name> if needed
    container_name: bcs
    restart: unless-stopped
    volumes:
      - ./bcs.yml:/app/bcs.yml:ro          # required configuration
      - ./logback.xml:/app/logback.xml:ro  # optional logging config
    # command: ["--run-once"]              # uncomment to run once and exit
    environment:
      - LOGGING_CONFIG=/app/logback.xml    # required configuration
    #   JAVA_TOOL_OPTIONS: -Xms128m -Xmx512m
    # user: "1000:1000"                    # drop root if desired

Start the service:

docker compose up -d

Run the container once and exit:

docker compose run --rm bcs --run-once

by Command Line

Download the last release jar.

The start by command line looks like:

cd /opt/bcs/
java -jar bcs.jar --logging.config=logback.xml --run-once

If you want the application to execute the birthday calendar synchronization only once and then exit immediately, you can use the --run-once parameter (one-time processing).

by systemd Service

BCS can also be started easily as a systemd service. An example for the desired service configuration can be found at the documentation systemd Service Configuration.

by init.d Service

Another possibility to start BCS is as init.d service. Further information can be found at the documentation of spring boot, Installation as an init.d Service (System V).