Installer Guide

Complete guide for the Reldens web-based installation wizard: storage drivers and clients, the installation steps, the form options, the installer classes, troubleshooting and re-installation.

For the user-facing "how to install Reldens" walkthrough (commands, requirements, basic configuration), see Installation.

Overview

The Reldens installer (lib/game/server/installer.js) provides a web-based GUI for setting up new Reldens installations. It handles database setup, entity generation, storage driver configuration, and project file creation.

Accessing the Installer

The installer runs automatically on the first launch when no installation lock file exists:

node .
# Navigate to http://localhost:8080 (or configured host/port)

A project created with reldens createApp has no start script in its package.json (ThemeManager.updatePackageJson() does not add one), so it is started with node . from the project root.

The installer will automatically redirect to the installation wizard if the project has not been installed yet.

Storage Drivers and Database Clients

Knex is the default storage driver and the only one bundled with @reldens/storage. The Storage Driver select lists every driver (knex, kysely, drizzle, objection-js, mikro-orm, prisma) with knex selected by default. A driver whose packages do not resolve from the project node_modules (StorageDriversResolver.available() from @reldens/cms) is listed with the " (will be installed)" label suffix.

With the "Allow installer to run npm install for missing packages" checkbox (app-allow-packages-installation) checked, the default, the installer installs the packages of the selected driver from the registry in lib/game/server/installer/storage-driver-packages.js. With the checkbox unchecked a driver whose packages are missing stops the installation with the driver-packages-missing error, so install them yourself first:

knex (default, always available)
- Clients: MySQL (native) / MySQL2 (recommended, automated installation), plus the manual clients pg, sqlite3, better-sqlite3, mssql, oracledb, cockroachdb.
kysely - npm install kysely
- Clients: MySQL / MySQL2 (automated installation).
drizzle - npm install drizzle-orm
- Clients: MySQL / MySQL2 (automated installation).
objection-js - npm install objection@3.1.5
- Clients: same clients as Knex.
mikro-orm - npm install @mikro-orm/core@7.2.0 @mikro-orm/mysql@7.2.0 (plus @mikro-orm/mongodb when the client is MongoDB)
- Clients: MySQL (automated installation), plus the manual clients mariadb, postgresql, sqlite, mongodb, mssql, better-sqlite3.
prisma - npm install prisma @prisma/client @prisma/adapter-mariadb (the adapter is the RELDENS_PRISMA_ADAPTER package)
- Clients: MySQL (automated installation), plus the manual clients postgresql, sqlite, sqlserver, mongodb, cockroachdb.

The client list per driver lives in install/index.js (DB_CLIENTS_MAP). The default client is mysql2 for the Knex based drivers and mysql for MikroORM and Prisma.

Automated vs Manual Installation

Automated installation (MySQL only)

Only MySQL clients (mysql, mysql2) support the automated installation scripts:

Creates database tables via reldens-install-v4.0.0.sql.
Installs basic configuration via reldens-basic-config-v4.0.0.sql (if checked).
Installs sample data via reldens-sample-data-v4.0.0.sql (if checked).
Generates entities from database schema.
Creates project configuration files.

Manual installation (all other clients)

Clients marked (manual) require manual database setup:

Installer skips SQL script execution (it logs "Non-MySQL client detected ({client}), skipping automated SQL scripts.").
User must manually create database tables and schema.
Installer generates entities from existing database.
Installer creates project configuration files.

Manual setup process:

Select a manual client from the installer.
Complete the installation wizard.
Manually execute SQL scripts or create schema in your database:
- Copy SQL files from the migrations/production/ directory.
- Adapt SQL syntax for your database (if needed).
- Execute scripts in order: install, basic-config, sample-data.
Run entity generation: reldens generateEntities --override.
Restart the application.

Installation Process Flow

Form validation
- The admin and the signed tokens secrets must not be empty (see "App settings" below).
- The driver key must exist in the @reldens/storage DriversMap (error invalid-driver).
Package installation (when the packages installation checkbox is checked, the default)
- Status: "Checking and installing required packages..."
- Installs or links reldens and the linkablePackages (see PackagesInstallation below) depending on RELDENS_INSTALLATION_TYPE.
- Installs the selected storage driver packages (PackagesInstallation.driversPackages, the Prisma driver installs prisma, @prisma/client and the RELDENS_PRISMA_ADAPTER package).
- Installs the selected mailer service package (nodemailer or @sendgrid/mail, from MailerServiceRegistry).
- A failed npm command stops the installation with the installation-dependencies-failed error.
Packages availability
- The selected driver packages must resolve from the project (error driver-packages-missing).
- The selected mailer service package must resolve from the project or the Reldens module (error mailer-packages-missing).
- The driver modules are loaded and attached to the data server config (knexModules, kyselyModules, etc.).
Database connection
- Status: "Configuring database connection..."
- Tests connection with provided credentials.
Driver installation
- Status: "Installing database driver: {driver}..."
- Executes SQL migration scripts through the data server rawQuery.
- Creates tables, basic config, sample data (MySQL clients only).
Entity generation
- Status: "Generating entities from database schema..."
- EntitiesInstallation runs the @reldens/storage EntitiesGenerator on the connected data server.
- Writes generated-entities/entities/, generated-entities/models/{driver}/, entities-config.js and entities-translations.js.
- Prisma only: generates prisma/schema.prisma and prisma/client (npx prisma db pull, npx prisma generate), writes prisma.config.js at the project root, and builds the prismaModules used by the generator and the runtime.
Project files
- Status: "Creating project files..."
- Creates .env, .gitignore, install.lock, and knexfile.js for the Knex based drivers (knex, objection-js).
- Cleans the sample assets when the sample data was not installed.
- Runs the startCallback inside ProjectFilesCreation.createProjectFiles() (the ServerManager reloads the new .env and starts the game server) and waits for it.
Completion
- Status: "Installation completed successfully!", written after createProjectFiles() returns, so after the startCallback finished.
- Redirects to the game (app-host plus : plus app-port).

The end of Installer.executeInstallProcess():

let filesCreation = await this.projectFilesCreation.createProjectFiles(
    templateVariables,
    storageDriverKey,
    dbDriver
);
if(!filesCreation.success){
    return res.redirect('/?error='+filesCreation.error);
}
this.updateInstallStatus('Installation completed successfully!');
return res.redirect(templateVariables['app-host']+':'+templateVariables['app-port']);

Status Tracking

The installer provides real-time status updates during installation:

Status file: install/install-status.json inside the project root
Format: {message: string, timestamp: number}
Frontend polls every 2 seconds
Status messages appear beside/below the loading image

Status messages:

"Starting installation process..."
"Checking and installing required packages..."
"Configuring database connection..."
"Installing database driver: {driver}..."
"Generating entities from database schema..."
"Creating project files..."
"Installation completed successfully!"

Configuration Options

App settings

Host - server host URL (e.g. http://localhost)
Port - server port (default: 8080)
Public URL - public-facing URL (for reverse proxies)
Trusted Proxy - reverse proxy address
Admin Panel Path - admin interface route (default: /reldens-admin)
Admin Panel Secret Key - signs the administration panel session (RELDENS_ADMIN_SECRET), required and not prefilled, the administration panel is not activated with an empty secret
Signed Tokens Secret Key - signs the reset password links and the multi-server disconnection requests (RELDENS_SIGNED_TOKENS_SECRET), required and not prefilled
An empty secret redirects back to the form (db-installation-process-failed-missing-admin-secret or db-installation-process-failed-missing-signed-tokens-secret) before the driver validation and any database work, so a missing secret never leaves a partial installation
Hot-Plug - enable runtime configuration reload
Allow installer to run npm install for missing packages - checked by default (app-allow-packages-installation), enables the package installation step of the flow above

Storage settings

Storage Driver - every driver, knex selected by default, the drivers with missing packages show the " (will be installed)" suffix
Client - database client library (see list above)
Host - database server host
Port - database server port
Database Name - database name
Username - database user
Password - database password
Install minimal configuration - MySQL only
Install sample data - MySQL only

The form defaults are read from the environment when present: RELDENS_APP_HOST, RELDENS_APP_PORT, RELDENS_PUBLIC_URL, RELDENS_EXPRESS_TRUSTED_PROXY, RELDENS_ADMIN_ROUTE_PATH, RELDENS_HOT_PLUG, RELDENS_STORAGE_DRIVER, RELDENS_DB_CLIENT, RELDENS_DB_HOST, RELDENS_DB_PORT, RELDENS_DB_NAME.

Optional features

HTTPS - SSL/TLS configuration
Monitor - Colyseus monitoring tools
Mailer - service select with None (preselected), NodeMailer and SendGrid; with packages installation allowed the selected service package (nodemailer or @sendgrid/mail) is installed the same way as the driver packages, None writes RELDENS_MAILER_ENABLE=0, and a selected service whose package is not found stops the installation with the mailer-packages-missing error
Firebase - Firebase authentication integration

Installer Architecture

Core classes

Installer (lib/game/server/installer.js)
- Main orchestration class.
- Handles Express routes and form processing.
- Renders the storage drivers list with storageDriversOptions() (every driver, the ones with missing packages with the " (will be installed)" suffix).
- Checks the admin and signed tokens secrets first, then validates the driver availability (isStorageDriverAvailable()) and attaches the driver modules (appendDriverModules()).
- Coordinates sub-installers.
- Manages status tracking.
GenericDriverInstallation (lib/game/server/installer/generic-driver-installation.js)
- Handles every non-Prisma driver installation (Knex, Kysely, Drizzle, ObjectionJS, MikroORM).
- Executes SQL migrations via rawQuery().
- Checks client type and skips non-MySQL scripts.
PrismaInstallation (lib/game/server/installer/prisma-installation.js)
- Handles Prisma-specific installation.
- Runs the SQL scripts in a forked subprocess.
- Builds the prismaModules with MySQLInstaller.createPrismaClient() from @reldens/cms.
PrismaSubprocessWorker (lib/game/server/installer/prisma-subprocess-worker.js)
- Forked child process for Prisma installation.
- Isolates Prisma client to avoid module caching.
- Generates the minimal Prisma client, writes prisma.config.js and runs the SQL scripts.
- The @reldens/storage schema generator builds the connection string from the installer configuration into RELDENS_DB_URL (setDatabaseEnvironmentVariables()) and writes prisma.config.js (generateConfigFile()), which reads that variable; the generated schema.prisma datasource block only has the provider, no url, as required by Prisma 7.
EntitiesInstallation (lib/game/server/installer/entities-installation.js)
- Generates entity classes from database schema for every driver.
- For Prisma, regenerates the schema and client first (preparePrismaSchema()).
ProjectFilesCreation (lib/game/server/installer/project-files-creation.js)
- Creates the .env file with configuration.
- Creates knexfile.js for the Knex based drivers.
- Creates .gitignore and install.lock.
- Runs the assets cleanup and then the start callback, before the installer writes the completion status.
PackagesInstallation (lib/game/server/installer/packages-installation.js)
- Manages npm package installation and linking based on RELDENS_INSTALLATION_TYPE.
- Runs installs before links so the main package link is always restored last.
- Installs the selected storage driver packages (the registry in lib/game/server/installer/storage-driver-packages.js: kysely, drizzle-orm, objection 3.1.5, @mikro-orm/core and @mikro-orm/mysql 7.2.0, and for Prisma prisma, @prisma/client and the RELDENS_PRISMA_ADAPTER package) and the selected mailer service package.
- The linkable packages (linkablePackages) are exactly @reldens/cms, @reldens/game-data-generator, @reldens/items-system, @reldens/modifiers, @reldens/server-utils, @reldens/skills, @reldens/storage, @reldens/tile-map-generator and @reldens/utils; the other Reldens dependencies (for example @reldens/tileset-to-tilemap) are not in the list, they resolve from the linked reldens package own node_modules.

Installation types (RELDENS_INSTALLATION_TYPE)

normal - installs reldens from npm registry; no linking.
link - npm links reldens and the linkablePackages above; no npm installs.
link-main - npm installs the linkablePackages above from registry, then npm links reldens last to restore the local source junction.

Package processing details: for the link and link-main types unlinkAllPackages() first removes the existing links. checkAndInstallPackages() then runs the installs first and the links after, so migrations/production/ resolves correctly through the link to the local source SQL files. Each install uses the version found in the reldens package lock file (node_modules/reldens/package-lock.json) when it can be read, otherwise the pinned registry version, and the packages already installed or linked are skipped.

Frontend files

install/index.html
- Installation form with all configuration fields.
- Storage driver select rendered from the storageDrivers template list.
- Client dropdown populated by JavaScript.
- Form validation and submission.
install/index.js
- Database client mapping (DB_CLIENTS_MAP).
- Dynamic client dropdown updates.
- Status polling functionality.
- Form submission handling.
install/css/styles.scss - installer styling.

Runtime Storage Initialization

After the installation (and on every start) DataServerInitializer.initializeEntitiesAndDriver() (lib/game/server/data-server-initializer.js) resolves the driver modules for RELDENS_STORAGE_DRIVER with the @reldens/cms StorageDriversResolver, builds the Prisma modules from prisma/client and the adapter when needed, and instantiates the data server from the @reldens/storage DriversMap.

MySQL-Only Scripts

The following SQL migration files only work with MySQL:

migrations/production/reldens-install-v4.0.0.sql
migrations/production/reldens-basic-config-v4.0.0.sql
migrations/production/reldens-sample-data-v4.0.0.sql

For other databases, these scripts must be manually adapted to the target database syntax.

Troubleshooting

"The selected storage driver packages were not found in the project"

Cause: the driver was selected but its packages are not installed in the project node_modules (and the packages installation was not allowed, or did not install them).

Solution:

Check "Allow installer to run npm install for missing packages" so the installer installs them, or install the packages listed in the "Storage Drivers and Database Clients" section yourself.
Submit the installer form again.

"Non-MySQL client detected, skipping automated SQL scripts"

Cause: selected a manual database client (PostgreSQL, SQLite, MongoDB, etc.).

Solution:

Complete the installer wizard.
Manually set up the database schema.
Run entity generation.
Restart the application.

"Connection failed, please check the storage configuration"

Cause: invalid database credentials or unreachable database server.

Solution:

Verify the database server is running.
Check host, port, username, password.
Ensure the database exists.
Check firewall/network settings.

"Entities generation failed"

Cause: database schema not found or invalid.

Solution:

For MySQL: ensure the installation scripts ran successfully.
For manual clients: verify you created all required tables.
Check the database connection.
Ensure the user has schema read permissions.

"Required packages installation failed"

Cause: npm install failed or network issues.

Solution:

Check the internet connection.
Manually run: npm install reldens.
Install the selected driver packages listed in the "Storage Drivers and Database Clients" section (for Prisma: npm install prisma @prisma/client @prisma/adapter-mariadb).
Check the npm logs for errors.

Post-Installation

After a successful installation:

The application redirects to the game.
The lock file is created at the project root (install.lock).
The installer becomes inaccessible.
Use the admin panel for further configuration.
Access the admin at the configured path (default: /reldens-admin).
Log in with the email and password of a user whose role is the server/admin/roleId config (99 in the basic configuration). The basic configuration seeds the root user (root@yourgame.com, role 99): change its password with reldens resetPassword --user=root --pass=..., or create a new admin with reldens createAdmin --user=... --pass=... --email=... (see Commands Reference). The admin secret key (RELDENS_ADMIN_SECRET) is not a login credential, it signs the administration panel session.

Re-installation

To re-run the installer:

Stop the application.
Delete the installation lock file (install.lock in the project root).
Optionally drop and recreate the database.
Start the application and navigate to the installation wizard.