ical-git is a minimalistic calendar application daemon written in Go. It reads a directory of iCalendar files (normally the files are directly fetched from your private git repository) and generates custom notifications based on the icalendar alarm definitions or default alarms defined in the config file.

Content

• Usage
• Features
• Installation
  • Binary
    • Get the binary
    • Build Manually
  • systemd Service File
  • Ical files
  • Configuration file
• Managing iCal Files
• Command line options

Usage

The basic usage involves having a private repository containing iCalendar .ics files. You need to provide the SSH key and repository address in the configuration TOML file. Alternatively, you can provide a path in the current filesystem. For more details, refer to the configuration file documentation. Once configured, you can run the daemon to start processing the calendar events.

Features

• Private Hosted Solution: Designed to provide a simple and effective private self-hosted calendar solution.
• Low resources computers: Supports installation on Raspberry Pi Zero and other cheap microcomputers.
• Notifications: Offers support for Telegram bots and local Linux desktop notifications.
• Direct Git Fetching: Can fetch iCal files directly from a git repository without saving them locally.
• Alarm Support: Supports alarms defined in the calendar .ics files and defined in the config. Alarms defined in the calendar .ics files have priority.
• Systemd Integration: Facilitates seamless integration with systemd for service management and logging.

Installation

Binary

Get the binary

On Linux, macOS, FreeBSD you can use the pre-built binaries

If your system has a supported version of Go, you can build from source

go install github.com/revelaction/ical-git/cmd/ical-git@latest

Move the binary to a suitable path

mv incal-git /home/icalgit/bin/ical-git
chmod +x /home/icalgit/bin/ical-git

Build Manually

To build ical-git manually from the source code, follow these steps:

1. Clone the Repository: Clone the ical-git repository to your local machine.

   git clone https://github.com/revelaction/ical-git.git
   cd ical-git

2. Build the Binary: Use go build with ldflags to include the Git tag in the binary.

   go build -ldflags "-X main.BuildTag=$(git describe --tags)" ./cmd/ical-git

3. Move the Binary: Move the built binary to a suitable path and set the executable permission.

   mv ical-git /home/icalgit/bin/ical-git
   chmod +x /home/icalgit/bin/ical-git

systemd Service File

For instructions on setting up and managing the systemd service file, see the systemd.md file.

Configuration file

Copy the TOML configuration file to the working directory specified in WorkingDirectory.

cp icalgit.toml /home/icalgit/icalgit

If you prefer to store the TOML file in a different location, specify the path in the ExecStart line of the systemd service file:

[Service]
User=icalgit
Group=icalgit

Type=simple
WorkingDirectory=/home/icalgit/icalgit
ExecStart=/home/icalgit/bin/ical-git --config /path/to/my-file.toml
Restart=on-failure
TimeoutSec=10

For a description of the configuration icalgit.toml file, see the Configuration File section.

ical files

The preferred method for managing iCal files is to use a private Git repository. Provide the SSH key and repository address in the TOML file under fetcher_git.

[fetcher_git]
private_key_path = "/path/to/ssh/key"
url = "git@github.com:yourusername/your-repo.git"

Alternatively, you can specify a path to a local filesystem directory containing your iCal files. This method is useful for testing or when you prefer to manage your iCal files locally. Note that using a local filesystem directory means that only one instance of the daemon can work with the files at a time.

[fetcher_filesystem]
directory = "/path/to/local/ical/files"

Managing iCal Files

For instructions on managing iCal files, see the Managing iCal Files section.

Command line options

    ical-git [-c CONF_FILE] 

Options:
    -c, --config                load the configuration file at CONF_FILE instead of default
    -v, --version               Print the version 
    -h, --help                  Show this help

CONF_FILE is the toml configuration file 

ical-git will react to a SIGHUP signal reloading the configuration file.

Examples:
    $ ical-git --config /path/to/config/file.toml # start the daemon with the configuration file
    $ ical-git -v  # print version`