NPM Installation

The Sync-in server can be installed via NPM and managed using a Command Line Interface (CLI).

It is designed to run in Linux-based environments (Debian, Ubuntu, AlmaLinux, Rocky Linux, etc.) as well as in BSD-based environments (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 – 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 or higher – 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 'strongpassword';

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://root:MySQLRootPassword@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. 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.

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

---

🖥️ Server CLI Commands

Command	Description
npx sync-in-server init	Copies the default config file environment.yaml
npx sync-in-server start	Starts the server in attached mode
npx sync-in-server start -d	Starts the server in detached mode (daemon)
npx sync-in-server stop	Stops the server
npx sync-in-server status	Shows the server status (daemon mode only)
npx sync-in-server version	Displays the installed version
npx sync-in-server migrate-db	Runs database migrations
npx sync-in-server update	Updates the server to the latest available version
npx sync-in-server create-user	Create a user or administrator in the database
npx sync-in-server help	Displays help and the list of available commands

info

The --prefix option can be added to any command if you're running npx sync-in-server from a directory other than where it was installed.

tip

npx sync-in-server update also runs database migrations automatically.