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

Follow these steps to test the backend server on your machine before moving to production.

• Navigate to the backend directory.
• Install dependencies using npm.
• Configure Database: Update your .env credentials (see Setup below).
• Start Server: Use the npm start script to launch.

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

# 2. Install dependencies
npm install

# 3. CONFIGURE CREDENTIALS FIRST
# Open .env and update DB settings (see below) before proceeding!

# 4. Start the server
npm start

The backend requires a valid database connection and environment configuration to function.

• 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., "viewsoft_backend") on your server before the app can sync tables.
• Custom Credentials: Update the .env file with your specific database host, user, and password.
• Restart Required: After changing .env values, restart the DB backend process or Windows service before retesting.

# 1. Create your environment file
copy .env.example .env

# 2. Configure .env with your credentials
PORT=5203
ALLOWED_ORIGIN=*

DATABASE_TYPE=mysql # mssql | mysql | postgres
DB_HOST=localhost
DB_USER=root
DB_SSL=false
DB_PASSWORD=your_password
DB_NAME=viewsoft_backend

After the database connection is configured, run the seed script to populate the required common records for the DB backend setup.

Once the seed completes, restart the DB backend again so the application reloads with the completed setup data.

• Run the seed command from the DB backend installation directory.
• Use the same environment configuration you prepared in the previous step.
• After seeding, restart whichever DB backend runtime you use before validation: local Node process, NSSM service, or another service manager.

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

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

# 3. Restart the DB backend after seeding (local development)
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 ViewsoftBackend "C:\Program Files\nodejs\node.exe" "server.js"
nssm set ViewsoftBackend AppDirectory "C:\Program Files\ViewsoftBackend"
nssm start ViewsoftBackend

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\viewsoft-backend`.
• Add an Application in IIS: Name it `Viewsoft 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\viewsoft-backend\web.config` with the reverse proxy rule below.

<!-- Create C:\inetpub\viewsoft-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 ViewsoftBackend` 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 CORS_ORIGIN environment variable in NSSM to match your domain.