(Subcategories required) Quick Start: Deploying via Docker (Single Instance)

This guide explains how to install and deploy the Nextcloud Exchange Connector in a Single-instance architecture using Docker.

Pre-requirements

Before deploying the application, ensure the following dependencies are ready and reachable by the connector:

The Nextcloud service account details are available (Configuring Nextcloud)
The Exchange service account or app registration details are configured (Configuring Exchange - TO ADD LINK TO SUBCATEGORIES)
A supported database is available and reachable from the application

Which databases are supported?

PostgreSQL (PostgreSQL official installation guide)
Microsoft SQL Server (Microsoft SQL Server official installation guide)
MariaDB (MariaDB official installation guide)
MySQL (MySQL official installation guide)

Docker is installed on your host machine (Docker official installation guide)
You have downloaded the deployment files containing the Nextcloud Exchange Connector release from the official GitHub repository.

Step 1. Prepare the Deployment Files

Extract the Sendent deployment files into your installation directory.

You do not need to alter the docker-compose.yml file.

All necessary configurations are managed entirely through environment variables (.env file).

The provided configuration will automatically pull the latest official container image from the public repository: rg.nl-ams.scw.cloud/sendent-public/sendent-sync:latest

Step 2. Configure the Environment Variables (`.env`)

Why this is needed: The application requires credentials and connection strings to communicate with Nextcloud, Exchange, and your database.

Create the .env file by copy-pasting the following code in the same directory as your Docker compose files:

.env Code

# Nextcloud Configuration
 
Service__NextcloudConfiguration__NextcloudBaseUrl=your-nextcloud-base-url
Service__NextcloudConfiguration__NextcloudServiceUsername=your-nextcloud-admin
Service__NextcloudConfiguration__NextcloudServicePassword=your-nextcloud-password
Service__NextcloudConfiguration__SharedSecret=your-shared-secret
 
# Exchange Configuration
 
# Allowed Exchange Types: Cloud(1), OnPremKerberos(2), OnPremBasicAuth(3), OnPremADFS(4)
 
Service__ExchangeConfiguration__ExchangeType=1
Service__ExchangeConfiguration__ExchangeOnPremUrl=https://outlook.office365.com/EWS/Exchange.asmx
Service__ExchangeConfiguration__ExchangeOnPremDomain=your-domain
Service__ExchangeConfiguration__ExchangeOnPremAdfsAuthorityUrl=your-adfs-authority-url
Service__ExchangeConfiguration__ExchangeTenantId=your-exchange-tenant-id
 
Service__ExchangeConfiguration__ExchangeAdminFile=
 
# Logging (Serilog & Loki)
 
# Change global Log level: Debug, Information, Warning, Error
 
Serilog__MinimumLevel__Default=Error
#Change Logs output: None(0), Console(1), Database(2), File(4), Grafana(8)
 
# You can combine outputs, just place sum of necessary numbers in this property
 
Service__LoggingConfiguration__LogsOutput=3

To understand the meaning of each parameter in .env file, refer to the Configuring the .env File.

Warning: Escaping Special Characters in Docker

When configuring passwords, connection strings, or secrets in your .env file, be aware of Docker's character constraints. Specifically, the dollar sign ($) is reserved for variable interpolation. If your actual password contains a literal $, you must escape it by doubling the character (e.g., a password of Pa$word must be written as Pa$$word in the .env file).

Failure to escape this will cause Docker to drop the character, resulting in severe authentication errors.

Warning: Shared Secret Mismatch

Your Service__NextcloudConfiguration__SharedSecret value must exactly match the shared secret configured in the Sendent Sync app within your Nextcloud web interface.

Warning: Strict File Naming

The environment file must be named exactly .env with no prefix. Naming the file like settings.env will cause Docker to fail to read the configuration.

Step 3. Set Up Exchange Credentials (`admins.json`)

Inside your deployment folder, create a directory named exchangeAdmins and place your admins.json file inside it. Update your .env file to point to this file (e.g., Service__ExchangeConfiguration__ExchangeAdminFile=globalAdmins/admins.json).

Pro Tip for Environments: You can organize multiple JSON files in subfolders (e.g., testAdmins/admins.json or globalAdmins/admins.json). To switch environments, simply update the file path in your .env variable without needing to rebuild or rewrite files.

Warning: Do Not Mix Exchange Types

Do not mix different Exchange connection types (e.g., Cloud and On-Premise) in a single admins.json file. The application instance connects to one specified Exchange type at a time. The "ExchangeType" field inside the admins.json.example file acts merely as a visual comment. The actual active connection type is dictated strictly by the Service__ExchangeConfiguration__ExchangeType parameter in your .env file.

Refer to Managing Service Accounts (admins.json) article to know more about managing service accounts.

Step 4. Start the Application

These commands tell Docker to pull the required images, map the volumes, and start the containers in the background.

The Sendent deployment is modular. You must build your startup command by chaining -f flags depending on which database and monitoring tools you want Docker to host for you.

Build your command by starting with the base file, adding your optional components, and ending with up:

1. The Base Command (Required): docker compose -f docker-compose.yml

2. Append your Database Container (Optional if using an external DB):

For PostgreSQL: -f docker-compose.postgres.yml
For MariaDB: -f docker-compose.mariadb.yml
For SQL Server: -f docker-compose.sqlserver.yml

3. Append Monitoring (Optional):

For Loki & Grafana: -f docker-compose.grafana.yml

Examples of complete commands:

Running with a local PostgreSQL container and Grafana:

docker compose -f docker-compose.yml -f docker-compose.postgres.yml -f docker-compose.grafana.yml up

Running with an external database (no local DB container) and no Grafana:

docker compose -f docker-compose.yml up

Step 5. Verify Container Status

Why this is needed: To ensure the primary synchronization service and your database containers are running without startup crashes.

Run the following command in your terminal:

docker compose ps

Step 6. Monitor Application Logs

Why this is needed: Logs are essential for verifying successful synchronization, reviewing scheduled runs, and troubleshooting errors.

To view real-time console logs, your Service__LoggingConfiguration__LogsOutput parameter in the .env file should be set to 1

Run:

docker compose logs

For comprehensive instructions on configuring alternative logging methods (such as Grafana or File System), please refer to Logging & Monitoring [TO INSERT THE SUBCATEGORY LINK HERE AFTER FULL DOCUMENTATION APPROVAL].

For handling self-signed certificates in On-Premise Exchange setups, see Advanced: Handling Self-Signed Certificates (On-Premise Exchange) article.

Next Step

Logging & Monitoring [TO INSERT THE SUBCATEGORY LINK HERE AFTER FULL DOCUMENTATION APPROVAL]

(Subcategories required) Quick Start: Deploying via Docker (Single Instance)

Pre-requirements

Step 1. Prepare the Deployment Files

Step 2. Configure the Environment Variables (.env)

Step 3. Set Up Exchange Credentials (admins.json)