Skip to main content

V2 Migration Guide

This guide is intended to assist with migrating Sync-in from version 1.x to version 2.x.

Server Upgrade​

The steps to follow depend on the installation method selected when deploying Sync-in.

Docker Compose​

Server​

To update the Docker image, edit the docker-compose.yaml file and set the image version to 2:

services:
  sync_in:
    image: syncin/server:2

Then apply the service update:

docker compose pull sync_in && docker compose up -d && docker image prune -f

Desktop applications repository (optional)​

If you are using it, edit docker-compose.sync-in-desktop-releases.yaml and set the image version to 2:

services:
  sync_in_desktop_releases:
    image: syncin/desktop-releases:2

Then run the ./config/sync-in-desktop-releases/update.sh command from the directory containing the docker-compose.yaml file.

Node Package Manager​

At the root of the NPM package, edit the package.json file and update the version to ^2.0.0:

{
  "dependencies": {
    "@sync-in/server": "^2.0.0"
  }
}

Then install the new package version:

rm -rf node_modules package-lock.json && npm install

Desktop Applications Upgrade​

Desktop applications running version 1.x remain compatible with a server running version 2.x for servers that were previously registered.

However, to re-authenticate or register servers from the applications, clients must be upgraded to version 2.x.

⚠️ Desktop applications running version 1.x will not automatically update to version 2.x.

You can download the latest version of the applications from the download page.

Breaking Changes​

Server Configuration​

Some sections of the environment.yaml configuration file have been reorganized and renamed to improve clarity and consistency.

  • The auth.method key has been renamed to auth.provider:
auth:
  # method: mysql
  provider: mysql
  • The auth.ldap.adminGroup key has been moved to auth.ldap.options.adminGroup:
auth:
  ldap:
    # adminGroup: admin
    options:
      adminGroup: admin

Improvements​

Reverse Proxy Configuration​

The Nginx configuration provided with the Docker Compose package has been simplified.
If you used the Nginx configuration template to adapt it to your reverse proxy, make sure to apply these changes or their equivalents in your configuration.

X-Forwarded-Proto Header Update​

  • The following directive must be used:

    proxy_set_header X-Forwarded-Proto $scheme;

  • It replaces the previous configuration:

    proxy_set_header X-Forwarded-Proto $xfp;

  • The section below can be removed from the configuration:

      map $request_uri $xfp {
        # This header must be null on webdav uri
        # It causes authentication failures with Microsoft-WebDAV-MiniRedir (Windows)
        ~^/webdav(?:/.*)?  "";
        default            $scheme;
      }

This simplification fixes certain WebDAV-related incompatibilities, reduces Nginx configuration complexity, and standardizes the handling of the X-Forwarded-Proto.