Skip to main content

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

:::warning 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, replace --role admin with --role user.

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.