Migrating from Legacy

This guide is for system administrators upgrading from the legacy Nextcloud Exchange Connector to the new architecture.

The new architecture represents a complete paradigm shift. The synchronization engine is no longer restricted by Nextcloud's internal cron jobs. It is now a powerful, decoupled microservice.

Because of this architectural upgrade, the way you configure the application has completely changed. You will no longer edit docker-compose.yml or appsettings.json. All settings have been unified into a single .env file, while administrator credentials have been moved to a dedicated admins.json file.

Prerequisites

Before starting the migration process:

1. Back up your database: Always create a full snapshot or dump of your existing database before performing major upgrades.

2. Keep your old config files handy: Do not delete your old docker-compose.yml or appsettings.json yet. You will need to copy the values from them during the mapping phase.

Step 1. Disable Legacy Background Tasks

If the legacy background synchronization tasks and the new worker run simultaneously, they will overwrite each other, causing massive duplication of calendar events and contacts.

You must stop the old synchronization engine from executing. Depending on how your legacy application was configured, you need to remove or disable the specific cron jobs (scheduled tasks) on your Nextcloud server that trigger the old synchronization scripts.

Step 2. Preserve Your Database

The new application is fully compatible with your existing database. Because the user tokens and synchronization watermarks are preserved in the old tables, migrating your database connection ensures a seamless transition:

• No massive "Initial Sync": The system will simply pick up exactly where it left off.

• No user re-consent required: Your Nextcloud users do not need to click the "Grant Access" button again. Their existing consent tokens will continue to work flawlessly.

Step 3. Prepare the Deployment Files

Download and extract the ready-to-use deployment files from the official Sendent GitHub repository into your installation directory.

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 4. The Configuration Mapping

You must manually translate your old configuration values into the new architecture using the .env file and the admins.json file.

environment:
  - Service__NextcloudBaseUrl=https://nc01.sendent.dev
  - Service__NextcloudServiceUsername=admin
  - Service__MicrosoftTenantId=df6e89a5-...
  - Service__ExchangeType=1
  - ConnectionStrings__DatabaseConnectionString=Host=sendent.synchronisation.db;Port=5432;...

Service__NextcloudConfiguration__NextcloudBaseUrl=https://nc01.sendent.dev
Service__NextcloudConfiguration__NextcloudServiceUsername=admin
Service__ExchangeConfiguration__ExchangeTenantId=df6e89a5-...
Service__ExchangeConfiguration__ExchangeType=1
DatabaseConfiguration__ConnectionString=Host=sendent.synchronisation.db;Port=5432;...

Step 4.1: General Settings (Move to .env)

Open your new .env file and map your old appsettings.json or docker-compose.yml variables exactly as follows:

Step 4.2: Administrator Credentials (Move to admins.json)

For security and scalability (to bypass Exchange throttling), direct credentials are no longer stored in the main environment file.

1. Inside your deployment folder, create a directory named exchangeAdmins.

2. Create a file named admins.json inside it.

3. Move your old credential variables into this JSON array depending on your Exchange connection type:

[
  {
    "AppId": "your_old_MicrosoftAppId_value",
    "ClientSecret": "your_old_MicrosoftClientSecret_value"
  }
]

[
  {
    "Username": "your_old_ExchangeOnPremUsername_value",
    "Password": "your_old_ExchangeOnPremPassword_value"
  }
]

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

Step 4.3: New Configuration Variables

The new architecture introduces several settings that were not present in the legacy appsettings.json or docker-compose.yml configurations. These new parameters provide granular control over scaling, data privacy, and logging.

You can configure these in your new .env file.

Step 5. Start the New Worker

Once your .env and admins.json files are fully mapped within your extracted deployment folder (from Step 3), and your legacy background processes are disabled, you can safely start the new worker.

The Sendent deployment is modular. You must build your startup command by appending -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, appending your optional components, and ending with up:

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

2. Append a Database Container (Skip if you're using an external database)

• 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

The application will automatically connect to your existing database, read the old tokens, and seamlessly resume synchronizing user data.

Step 6. Configure Logging

The logging architecture has been completely redesigned. You will no longer define complex Serilog objects in appsettings.json. Instead, you control logging through bitwise values in the .env file.

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].

Clean-up

After verifying that the new worker is running and synchronization is occurring smoothly via the logs, safely archive or delete your old docker-compose.yml and appsettings.json files to prevent future configuration confusion.