(Awaiting Approval) 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 a PHP-based plugin restricted by Nextcloud's internal cron jobs. It is now a powerful, decoupled .NET 8 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 the Legacy Application

Why this is needed: To prevent severe data corruption. If both the old PHP-based connector and the new .NET worker run simultaneously, they will aggressively overwrite each other and cause massive duplication of calendar events and contacts.

1. Log in to your Nextcloud server via SSH.

2. Navigate to your Nextcloud root directory.

3. Use the occ command to completely disable the legacy application before proceeding.

sudo -u www-data php occ app:disable <legacy_app_id>

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

Extract the ready-to-use deployment files from the ZIP archive provided by Sendent. - to ask Luc to advise on how the User will get the necessary files

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.

Part A: General Settings (Move to .env)

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

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

Part B: 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 5. Start the New Worker

Once your .env and admins.json files are fully mapped and your old Nextcloud app is disabled, you can safely start the new worker.

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

Clean-up

After verifying that the new V2 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.