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, 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 or higher – Install Node.js: nodejs.org/download

✅ Check the installed version:

node -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

Example: 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_unicode_ci;

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

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

FLUSH PRIVILEGES;

🚀 Installation

1. NPM Package

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

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

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