Ir al contenido principal

Instalación con Node Package Manager

Instalación del servidor Sync-in a través de NPM y la interfaz de línea de comandos (CLI).

El servidor está diseñado para ejecutarse en entornos basados en Linux (Debian, Ubuntu, AlmaLinux, Rocky Linux, etc.), así como en sistemas basados en BSD (FreeBSD, macOS, etc.).

⚠️ Los entornos Windows no son compatibles oficialmente.

📋 Requisitos previos​

Antes de instalar Sync-in, asegúrese de que su entorno cumpla con los siguientes requisitos:

🟢 Node.js​

Versión requerida: 22.12.0 o posterior – Instalar Node.js: nodejs.org/download

✅ Verifique la versión instalada de Node.js:

node -v

✅ Verifique la versión npm instalada (instálela si aún no está disponible):

npm -v

🛢️ MariaDB​

Versión requerida: 11.x – Instalar MariaDB: mariadb.org/download

✅ Verifique la versión instalada:

mariadb --version
información

El binario puede variar dependiendo de su sistema: use mysql o mariadb según corresponda.

Asegúrese de que:

  • El servicio MariaDB se está ejecutando.
  • El puerto 3306 está abierto si la base de datos es remota
  • Se ha creado manualmente una base de datos antes de iniciar el servidor.
Crear una base de datos local con un usuario dedicado

Conéctese a MariaDB como administrador (o root):

mariadb -u root -p

Luego ejecute los siguientes comandos:

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;
advertencia

Recordatorio importante sobre localhost en MariaDB

  • 'sync_in_user'@'localhost'

    • ➡ Conexión permitida solo desde la máquina que aloja MariaDB (a través de un socket Unix o una conexión TCP local).

  • 'sync_in_user'@'%'

    • ➡ Conexión posible desde cualquier dirección IP.
    • ⚠ Mayor riesgo: solo debe usarse para casos específicos, con una contraseña segura y filtrado de IP a nivel de firewall.

  • 'sync_in_user'@'IP' o 'sync_in_user'@'hostname'

    • ➡ Conexión limitada a esta dirección IP específica o a este nombre de host específico.
    • ✅ Opción recomendada para acceso remoto seguro.
Recomendación de ajuste
[mysqld]
innodb_ft_cache_size = 16000000 # 16MB
max_allowed_packet   = 1G

Detalles:

  • innodb_ft_cache_size: utilizado por InnoDB al crear o actualizar índices FULLTEXT. Los valores más altos aceleran la creación de índices a costa de un mayor uso de RAM.
  • max_allowed_packet: establece el tamaño máximo del paquete intercambiado entre el cliente y el servidor MariaDB. Resulta especialmente importante para BLOB grandes o exportaciones SQL voluminosas.

🚀 Instalación​

1. Paquete NPM​

Puede instalar el servidor Sync-in en una carpeta dedicada usando la opción --prefix de NPM:

Nota de instalación de FreeBSD

Asegúrese de que la biblioteca vips (versión ≥ 8.17.2) esté disponible antes de continuar. Cambie al repositorio de FreeBSD más reciente si es necesario.

  • Comando para comprobar la versión disponible:

    pkg rquery '%v' vips

  • Instalar dependencias de compilación:

    pkg install -y python3 gmake pkgconf llvm

  • Instalar la biblioteca vips:

    pkg install vips

  • Instale el servidor Sync-in:

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

Esto instalará el paquete del servidor en el directorio ./sync-in, con la siguiente estructura:

  • ./sync-in/node_modules/ → dependencias instaladas
  • ./sync-in/package.json → metadatos del paquete

2. Configuración​

El archivo de configuración del servidor environment.yaml debe estar ubicado en este directorio.

Para implementar una configuración mínima directamente en el entorno, puede utilizar la CLI sync-in-server:

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

o con el argumento --prefix:

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

Utilice la opción --prefix si ejecuta comandos CLI desde un directorio diferente al sync-in (usado aquí como ejemplo).

Edite el archivo ./sync-in/environment.yaml:

server:
  # Opcional por ahora; será obligatorio en la próxima versión principal
  publicUrl: 'https://sync-in.domain.com'
mysql:
  # Utilice el nombre de usuario y la contraseña que ha definido
  url: 'mysql://sync_in_user:sync_in_user_password@localhost:3306/sync_in'
auth:
  encryptionKey: 'REPLACE_WITH_LONG_RANDOM_ENCRYPTION_KEY'
  token:
    access:
      secret: 'REPLACE_WITH_LONG_RANDOM_ACCESS_SECRET'
    refresh:
      secret: 'REPLACE_WITH_LONG_RANDOM_REFRESH_SECRET'
URL pública

publicUrl debe coincidir con la dirección expuesta a los usuarios por el servidor o el proxy inverso, incluido el esquema y cualquier puerto no estándar. Sigue siendo opcional hasta la próxima versión importante. Se debe poder acceder a la URL desde los navegadores de los usuarios y, para los editores de Office que se comunican con Sync-in, desde sus servicios. Cuando se omite publicUrl, los editores utilizan el origen de la solicitud como respaldo de compatibilidad. Por motivos de seguridad, será obligatorio en la próxima versión principal, para que los endpoints de los editores se construyan a partir de un origen de confianza controlado por el administrador y no de los encabezados de las solicitudes.

Seguridad

Utilice cadenas largas y generadas aleatoriamente para sus secretos para garantizar la máxima seguridad.

información

No olvide incluir sus contraseñas entre comillas simples si contienen caracteres especiales.

consejo

Los parámetros escalares de configuración del servidor Sync-in se pueden definir mediante variables de entorno con el prefijo SYNCIN_; consulte la sección correspondiente.

3. Base de datos​

Desde el directorio sync-in, una vez configurado, inicialice la base de datos:

npx sync-in-server migrate-db

Resultado esperado:

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

4. Almacenamiento de datos​

Se configura una ruta predeterminada para almacenar todos los datos de la aplicación.

Esta ruta se puede personalizar editando el archivo environment.yaml, como se muestra a continuación:

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

5. Crear un administrador​

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

Para crear un usuario que no sea administrador, reemplace --role admin con --role user.

También están disponibles las siguientes opciones al crear la cuenta: --email, --first-name, --last-name, --permissions y --storage-quota. Utilice --permissions all para otorgar todos los permisos de usuario. --storage-quota se expresa en bytes; use 0 para almacenamiento ilimitado.

Si no establece estos argumentos y simplemente ejecuta:

npx sync-in-server create-user

el servidor utilizará las credenciales de administrador predeterminadas:

  • Identificador: sync-in
  • Contraseña: sync-in
advertencia

Importante: Por razones de seguridad, se recomienda encarecidamente cambiar estas credenciales al iniciar sesión por primera vez.

6. Iniciar el servidor​

Puede iniciar el servidor de dos maneras:

  • En primer plano (el proceso permanece asociado a su terminal):

    npx sync-in-server start

  • En modo independiente (demonio):

    npx sync-in-server start -d
    información

    En modo demonio, el proceso ya no está conectado a la consola del usuario.
    Los registros se escriben automáticamente en logs/server.log.
    La ruta del archivo de registro se puede personalizar en environment.yaml.