Installation

Installation of the Sync-in server via NPM and the command-line interface (CLI).

The server is designed to run on Linux-based environments (Debian, Ubuntu, AlmaLinux, Rocky Linux, etc.) as well as on BSD-based systems (FreeBSD, macOS, etc.).

⚠️ Windows environments are not officially supported.

---

📋 Prerequisites

Before installing Sync-in, make sure your environment meets the following requirements:

🟢 Node.js

Required version: 22.x – 24.x – Install Node.js: nodejs.org/download

✅ Check the installed Node.js version:

node -v

✅ Check the installed npm version (install it if it is not already available):

npm -v

🛢️ MariaDB

Required version: 11.x – Install MariaDB: mariadb.org/download

✅ Check the installed version:

mariadb --version

info

The binary may vary depending on your system: use mysql or mariadb as appropriate.

Make sure that:

• The MariaDB service is running
• Port 3306 is open if the database is remote
• A database has been manually created before launching the server

Create a local database with a dedicated user

Connect to MariaDB as administrator (or root):

mariadb -u root -p

Then execute the following commands:

CREATE DATABASE sync_in CHARACTER SET utf8mb4 COLLATE utf8mb4_uca1400_ai_ci;

CREATE USER 'sync_in_user'@'localhost' IDENTIFIED BY 'sync_in_user_password';

GRANT ALL PRIVILEGES ON sync_in.* TO 'sync_in_user'@'localhost';

FLUSH PRIVILEGES;

warning

Important reminder about localhost in MariaDB

• 'sync_in_user'@'localhost'

  • ➡ Connection allowed only from the machine hosting MariaDB (via Unix socket or local TCP connection).

• 'sync_in_user'@'%'

  • ➡ Connection possible from any IP address.
  • ⚠ Higher risk: should only be used for specific cases, with a strong password and IP filtering at the firewall level.

• 'sync_in_user'@'IP' or 'sync_in_user'@'hostname'

  • ➡ Connection limited to this specific IP address or hostname.
  • ✅ Recommended option for secure remote access.

Tuning recommendation

[mysqld]
innodb_ft_cache_size = 16000000 # 16MB
max_allowed_packet   = 1G

Details :

• innodb_ft_cache_size : Used by InnoDB when building or updating FULLTEXT indexes. Higher values speed up index creation at the cost of more RAM usage.
• max_allowed_packet : Sets the maximum packet size exchanged between the MariaDB client and server. In the case of large BLOBs or massive SQL exports.

---

🚀 Installation

1. NPM Package

You can install the Sync-in server in a dedicated folder using NPM's --prefix option:

FreeBSD Installation Note

Make sure the vips library (version ≥ 8.17.2) is available before proceeding. Switch to the latest FreeBSD repository if necessary.

• Command to check the available version:

  pkg rquery '%v' vips

• Install build dependencies:

  pkg install -y python3 gmake pkgconf llvm

• Install vips library:

  pkg install vips

• Install Sync-in server:

  npm install @sync-in/server node-addon-api node-gyp --prefix ./sync-in

npm install @sync-in/server --prefix ./sync-in

This will install the server package into the ./sync-in directory, with the following structure:

• ./sync-in/node_modules/ → installed dependencies
• ./sync-in/package.json → package metadata

2. Configuration

The server configuration file environment.yaml must be located in this directory.

To deploy a minimal config directly into the environment, you can use the sync-in-server CLI:

cd ./sync-in && npx sync-in-server init

or with the --prefix argument:

npx --prefix ./sync-in sync-in-server init

tip

Use the --prefix option if you run CLI commands from a different directory than sync-in (used here as an example).

Edit the file ./sync-in/environment.yaml:

auth:
  encryptionKey: "changeEncryptionKeyWithStrongKey"
  token:
    access:
      secret: "changeAccessWithStrongSecret"
    refresh:
      secret: "changeRefreshWithStrongSecret"
mysql:
  # Use the username and password you defined
  url: mysql://sync_in_user:sync_in_user_password@mariadb:3306/sync_in

Security

Use long and randomly generated strings for your secrets to ensure maximum security.

info

Don't forget to wrap your passwords in quotes if they contain special characters.

tip

All Sync-in server configuration parameters can be set using environment variables prefixed with SYNCIN_, see the relevant section.

3. Database

From the sync-in directory, once configured, initialize the database:

npx sync-in-server migrate-db

Expected output:

🗄️ Running database migrations...
Load configuration → environment.yaml
✅ Database migrations completed successfully.

4. Data Storage

A default path is configured to store all application data.

This path can be customized by editing the environment.yaml file, as shown below:

applications:
  files:
    dataPath: /home/sync-in/data

5. Create an administrator

npx sync-in-server create-user --role admin --login "userLogin" --password "userPassword"

tip

To create a non-admin user, remove the --role admin option.

If you do not set these arguments and simply run:

npx sync-in-server create-user

the server will use the default admin credentials:

• Login: sync-in
• Password: sync-in

warning

Important: For security reasons, it is strongly recommended to change these credentials upon first login.

6. Starting the server

You can start the server in two ways:

• In attached mode (the process stays attached to your terminal):

  npx sync-in-server start

• In detached (daemon) mode:

  npx sync-in-server start -d

  info

  In daemon mode, the process is no longer attached to the user console.
  Logs are automatically written to logs/server.log.
  The log file path can be customized in environment.yaml.