Tool to sync multiple calendars from different sources into one Free/Busy calendar 📆
About This Project · Features · Setup/Running · Docker · Resources

❓ About This Project

I started this project since I had the problem that there wasn't a publicly available (free) software that synchronized multiple calendars into one Free/Busy calendar. So I set out on a mission to develop such a tool. This tool uses multiple CalDav servers as input and copies all the busy/opaque events to one or multiple other calendars. The software is made to run in a Docker container on a refresh interval.

✨ Features

• Syncing Multiple Calendars Into Free/Busy Calendars
• Exporting Multiple Free/Busy Calendars
• Syncing Automatically On An Interval
• Adding Travel-Time To The Event
• Exporting Multiple Free/Busy Calendars With Visible Events

🛠️ Setup/Running

This section describes the basic setup and running of the software.

calsync [-c CONFIG] [-i INTERVAL] [-wb WEEKS_BACK] [-wf WEEKS_FORWARD]

Syncs calendars from multiple services into one busy/free calendar

optional arguments:
  -c CONFIG, --config CONFIG
                        Path to config file
  -i INTERVAL, --interval INTERVAL
                        Interval in minutes to sync
  -wb WEEKS_BACK, --weeks-back WEEKS_BACK
                        Number of weeks to sync back
  -wf WEEKS_FORWARD, --weeks-forward WEEKS_FORWARD
                        Number of weeks to sync forward

Some optional arguments can also be passed as environment variables:

• WEEKS_FORWARD = CALENDARSYNC_WEEKS_FORWARD
• WEEKS_BACK = CALENDARSYNC_WEEKS_BACK
• INTERVAL = CALENDARSYNC_INTERVAL

Note

When adding calendars to the calendars list that don't exist, you will get a warning, but the sync will proceed.

Note

If no or an invalid config is provided, a corresponding error occurs, but the sync will try to proceed.

Caution

Calendar names in the calendars, aggregate or visible list can't include ","

iCloud

1. Go to appleid.apple.com
2. Under Sign-In and Security go to App-Specific Passwords
3. Add a new Password and copy it to your config

[iCloud]
username=your@email.com         (Your iCloud Login E-Mail Address)
password=xxxx xxxx xxxx xxxx    (The App-Specific Password you just created)
calendars=Work,Private,...      (The Calendars you want to sync)
aggregate=Free/Busy,...         (The Calendars you want to aggregate to)
visible=Aggregated,...          (The Calendars you want to aggregate all events to as visible)
travel=True						(If Travel-Time should be included in the aggregated events)

Important

When adding a calendar to the aggregate or visible list, that doesn't exist, it will be created.

Google

1. Go to myaccount.google.com
2. Under Security select 2-Step Verification
3. At the bottom of the page select App passwords (this is only possible if 2-Step Verification is enabled)
4. Add a new password and copy it to your config

[Google]
username=gmail@email.com        (Your Google Login E-Mail Address)
password=xxxx-xxxx-xxxx-xxxx    (The App-Password you just created)
calendars=Work,Private,...      (The Calendars you want to sync)
aggregate=Free/Busy,...         (The Calendars you want to aggregate to)
visible=Aggregated,...          (The Calendars you want to aggregate all events to as visible)

Important

When adding a calendar to the aggregate or visible list, that doesn't exist, an error occurs and the sync will fail!

🐳 Docker

The easiest way to run the software is as a Docker container. There are 2 ways you can achieve this.

Note

With these configurations, the config.ini needs to be placed inside the settingsfolder

Important

If no or an invalid config is provided, a corresponding error occurs, but the sync will try to proceed and the container won't fail.

Command Line

docker build --tag calendarsync

# With Default Synchronization Values
docker run --name yourcontainername -v /path/to/settingsfolder:/app/settings calendarsync

# With Custom Synchronization Values
docker run --name yourcontainername -v /path/to/settingsfolder:/app/settings -e CALENDARSYNC_WEEKS_FORWARD=2 -e CALENDARSYNC_WEEKS_BACK=2 -e CALENDARSYNC_INTERVAL=15 calendarsync

Docker Compose

version: '3'

services:
  calendarsync:
    container_name: calendarsync
    build: .
    environment:
      - CALENDARSYNC_INTERVAL=15
      - CALENDARSYNC_WEEKS_BACK=2
      - CALENDARSYNC_WEEKS_FORWARD=2
    volumes:
      - /path/to/settingsfolder:/app/settings

📚 Resources

• Connection to Google Calendar
• CalDav Library

---

If you like this project, you can buy me a coffee 😄 Would be greatly appreciated!