Korga

Important

This README reflect the current development state on master for Korga 4. See Korga 3.1.3 for the latest released version.

Korga stands for the german term Kirchen Organisation (church organization). It synchronizes people and groups with ChurchTools and provides specialized features like email distribution lists.

What can Korga already do?

Email distribution lists

Korga makes it possible to send emails to ChurchTools groups via email. For example, anyone can send an email to [email protected] and Korga will forward it to all members of your ChurchTools group Youth with role Leader.

There is no Web UI available yet to manage distribution lists so you must stick to the CLI inside the Docker container:

./Korga dist create youth
./Korga dist add-recipient youth -g 137

This command creates a distribution list [email protected] which forwards emails to every member of group #137.

Installation

The only officially supported distribution are Docker containers. An official image is available at daniellerch/korga. If you are using Docker Compose, take a look our example compose file in the docs folder.

Korga has multiple modules that must be enabled via configuration to use them:

• ChurchTools sync
• Email delivery
• Email relay

See Korga server configuration for a full list of configuration options.

OAuth authentication

Korga uses single sign-on via OAuth 2.0. It is the only authentication mechanism Korga supports and required to start the application.

These instructions assume you use ChurchTools as OAuth provider (supported since December 2024). Other OAuth 2.0 and OpenID Connect identity providers should also work.

1. Login to ChurchTools as an administrator and open System settings from the navbar

2. Go to Integrations > Login to third-party system and click on Add OAuth-Client

3. Choose a name (will be displayed to users when they log in) and enter the URL of your Korga instance as Redirect-URI e.g. https://korga.example.org/api/signin-oauth

After creating an OAuth client for Korga in ChurchTools, you can configure it via environment variables in compose.yaml.

ChurchTools sync

First you must create a service account which Korga can use for API access to ChurchTools:

1. Create a person with email address in your ChurchTools instance
   You might want to define a special status for API users
2. Invite that person to ChurchTools
3. Click on the invitation link and set a password
4. Open https://example.church.tools/api/whoami to look up the ID of the newly created user
5. Open https://example.church.tools/api/person/${ID}/logintoken to look up the long-term access token which will be used like an API key

Steps 4. and 5. can also be performed in the ChurchTools web interface: Official Documentation

Warning

For security reasons it is not recommended to let Korga use your ChurchTools admin account.

Grant the following permissions to Korga's user:

• Administration > Berechtigungen anpassen churchcore:administer persons
• Personen & Gruppen > "Personen & Gruppen" sehen churchdb:view
• Personen & Gruppen > Sicherheitslevel Personendaten (Stufe 1-3) churchdb:security level person(1,2,3)
• Personen & Gruppen > Alle Personen des jeweiligen Bereiches sichtbar machen (Alle) churchdb:view alldata(-1)
• Personen & Gruppen > Einzelne Gruppen inkl. der enthaltenen Personen sehen (gilt auch für versteckte Gruppen) (Alle) churchdb:view group(-1)
• Personen & Gruppen > Gruppenmitgliedschaften aller sichtbaren Personen bearbeiten churchdb:edit group memberships
• Events > "Events" sehen churchservice:view
• Events > Dienste einzelner Dienstgruppen einsehen (Alle) churchservice:view servicegroup(-1)
• Events > Events von einzelnen Kalendern sehen (Alle) churchservice:view events(-1)

After creating and configuring a ChurchTools user for Korga you can finally configure it via environment variables in compose.yaml.

Do not forget to recreate your container to take these changes into effect.

Email delivery

Email delivery requires an SMTP server and credentials. This is given for almost any email inbox. Depending on your email hosting provider you might need an app password. Email delivery can be configured via environment variables in compose.yaml.

Email relay

Korga's email relay requires a catchall IMAP inbox. Such an inbox receives all emails sent to a domain where no matching inbox was found, i.e. *@example.org. It can be configured via environment variables in compose.yaml.

Contributing

Contributions are highly welcome. Please open an issue before implementing a feature to discuss your plans.

Korga's source code is split into the backend (located in server) and the frontend (located in webapp). The following instructions are written for Windows but generally also apply to Linux development setups.

Backend

• Visual Studio 2022
• .NET SDK 8.0
• EF Core CLI Tools (e.g. dotnet tool install -g dotnet-ef)
• MySQL or MariaDB (e.g. from PSModules)

Frontend

• Visual Studio Code
• Vue Language Features (Volar) Extension
• NodeJS 22 LTS

During development the frontend running on the Vue CLI development server will use http://localhost:10501 as API endpoint. That means the backend can be running in Visual Studio with Debugger attached.

If you just want to work on the frontend you can also use a public test server by creating a file webapp/.env.development.local

VITE_API_ORIGIN=https://lerchen.net
VITE_API_BASE_PATH=/korga/

Then you don't have to setup a database server and the ASP.NET Core backend.