Rasterex Backend (DB Backend)

The backend is a high-performance Node.js application. Before deployment, ensure the host server meets the following requirements.

• Node.js Runtime: Version 18.x or higher is recommended.
• Database Connectivity: Access to a SQL-compatible database (PostgreSQL, MySQL, or MSSQL).
• Network Ports: Port 5203 must be available for the Node process (default).

# Verify Node.js installation
node --version

# Ensure NPM is available
npm --version

The installed Rasterex Backend directory is C:\Program Files\RasterexBackend. Start there: it contains .env.example, which you copy to .env and configure before running the seed command or starting Rasterex Backend.

The database server must be running and reachable. Create the database when required, then configure the environment file with working credentials.

• Supported Databases (Enum): mssql, mysql, postgres.
• Environment File: Copy .env.example to .env to start.
• Project Database: You must manually create the database (e.g., "Rasterex_backend") on your server before the app can sync tables.
• Database settings: Update DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME, DB_SSL, and DATABASE_TYPE for the customer database.
• Canvas access: Set ALLOWED_ORIGIN to the full Canvas URL that will connect to the API.
• Admin access: Replace ADMIN_API_KEY with a private value before enabling administrative API access.
• Restart Required: After changing .env values, restart the DB backend process or Windows service before retesting.

# 1. Open the installed Rasterex Backend directory
cd "C:\Program Files\RasterexBackend"

# 2. Create the environment file supplied with the installed package
copy .env.example .env

# 3. Open .env and replace every placeholder with customer-specific values.
DB_HOST=your-database-host
DB_PORT=your-database-port
DB_USER=your-database-user
DB_PASSWORD=your-database-password
DB_NAME=your-database-name
DB_SSL=<true-or-false>
DATABASE_TYPE=postgres

# Backend listener and permitted Canvas origin
PORT=5203
ALLOWED_ORIGIN=https://your-canvas-host

# Keep this value private. Do not use this placeholder in a deployed environment.
ADMIN_API_KEY=replace-with-a-private-admin-key

Complete the database and environment setup above first. Install the backend dependencies before seeding the database.

• Navigate to the backend directory.
• Install the backend dependencies using npm.

# 1. Navigate to backend path
cd "C:\Program Files\RasterexBackend"

# 2. Install the backend dependencies
npm install

After the database server is reachable and .env contains working credentials, run the seed script to populate the required common records for the DB backend setup. The seed command connects to the configured database; it does not require the Rasterex Backend server to be running first.

For a first local setup, run this step before starting the DB backend server.

• Run the seed command from the DB backend installation directory.
• Use the same environment configuration you prepared in the previous step.
• If the DB backend is already running when you change .env or seed common data, restart it before validation.

# 1. Navigate to backend path
cd "C:\Program Files\RasterexBackend"

# 2. Seed common data
node seed-common.js

Start the server only after the database environment is configured and the common-data seed completes successfully. Then configure Canvas and use the local verification checklist.

# Run from the DB backend installation directory
npm start

When first running the server locally, you will likely encounter a "Database connection failed" error.

• Expected Failure: The default configuration uses placeholder credentials.
• Access Denied (1045): If you see "ER_ACCESS_DENIED_ERROR" or "SequelizeAccessDeniedError", your username/password/host in .env is incorrect.
• Database Not Found: Ensure the database schema ("DB_NAME") actually exists on your server.
• Solution: Open your .env file and provide working connection details for your database.
• Verification: The server will display "Database synchronized" once the connection is successful.

Deploying to production requires additional steps to ensure high availability, security (SSL), and persistent execution.

Enable the Windows features required to host the web interface and proxy API requests.

• Web Server (IIS): Core hosting environment.
• Application Request Routing (ARR): Required for Reverse Proxy functionality.
• URL Rewrite Module: Required for routing rules.

# Enable required Windows Features
Enable-WindowsOptionalFeature -Online -FeatureName IIS-WebServerRole, IIS-WebServer, IIS-StaticContent, IIS-DefaultDocument, IIS-HttpRedirect

Use the Non-Sucking Service Manager (NSSM) to wrap the Node.js application as a Windows Service, enabling automatic restarts and background execution.

• Install NSSM via Chocolatey before creating the service.
• Persistence: The service starts automatically with Windows.
• Resilience: Restarts immediately if the Node process crashes.
• Isolation: Runs under the LocalSystem or a dedicated Service Account.

# Create the backend service
choco install nssm -y
nssm install RasterexBackend "C:\Program Files\nodejs\node.exe" "server.js"
nssm set RasterexBackend AppDirectory "C:\Program Files\RasterexBackend"
nssm start RasterexBackend

Configure IIS to act as a gateway, forwarding requests from port 80/443 to the backend service. This involves creating an Application and a Rewrite Rule.

• Create a physical folder: C:\inetpub\Rasterex-backend.
• Add an Application in IIS: Name it Rasterex Backend, point it to the project folder, and attach it to the chosen site.
• If port 80 is already in use, create a new IIS site on a different port (for example 8081) and use that site for the backend application.
• Set App Pool: Use "No Managed Code".
• Create C:\inetpub\Rasterex-backend\web.config with the reverse proxy rule below.

<!-- Create C:\inetpub\Rasterex-backend\web.config -->
<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <rewrite>
            <rules>
                <rule name="ReverseProxyToBackend" stopProcessing="true">
                    <match url=".*" />
                    <action type="Rewrite" url="http://localhost:5203/{R:0}" />
                </rule>
            </rules>
        </rewrite>
    </system.webServer>
</configuration>

Enforce HTTPS for all production traffic. This ensures data integrity and satisfies modern browser security requirements.

• SSL Binding: Assign your certificate to port 443 in IIS Manager.
• Automatic Redirect: Force all HTTP requests to upgrade to HTTPS.

Before handing over the environment, perform these health checks to ensure end-to-end reliability.

• Local Health: Browse to http://localhost:5203/ (Service response).
• Proxy Health: Browse to https://yourdomain.com/ (IIS Gateway response).
• SSL: Ensure no "Insecure" warnings appear in the browser.
• NSSM: Run nssm status RasterexBackend to confirm "SERVICE_RUNNING".

Reference this section if you encounter connectivity issues during setup.

• 502.3 Gateway Error: Ensure ARR is enabled (Application Request Routing -> Server Proxy Settings).
• 404 Not Found (API): Ensure the IIS application is named exactly api.
• EADDRINUSE: Another process is using port 5203. Check with netstat -ano | findstr :5203.
• CORS Denied: Set the ALLOWED_ORIGIN environment variable to the full Canvas URL.