Skip to content

Installation Guide

Universal Installation & Operations Guide (Windows • Linux • macOS)

A comprehensive, step-by-step setup and lifecycle guide for installing, configuring, starting, stopping, and maintaining VistaBridge across Windows, Linux, and macOS.


1. Overview of the Setup Architecture

VistaBridge operates without .env files. Configuration details such as the GeoServer URL and JWT secret are stored directly in the embedded SQLite database: data/geovista.db.

VistaBridge uses the following scripts to manage installation and application operations:

  • Setup (setup.bat / setup.sh): Installs dependencies, configures the database, allows users to manage existing configuration settings, and compiles an optimized production build.
  • Start (start.bat / start.sh): Checks build health, frees port 3000, starts the server, and launches the browser.
  • Stop (stop.bat / stop.sh): Locates and terminates the background server process using port 3000.

When an existing database is detected, the Setup Wizard displays the current GeoServer URL and frontend port and provides options to retain, update, or reset the configuration.


2. Prerequisites (All Platforms)

Before installing VistaBridge, ensure the following requirements are met:

  • Node.js: Latest version of Node.js. Check the installed version using node -v. Download it from https://nodejs.org.
  • GeoServer: A running local, remote, or Docker instance, for example:
  • http://localhost:8080/geoserver
  • https://vistabridge.rottengrapes.tech/geoserver
  • Port 3000: Used by default for serving the VistaBridge web application. Ensure the selected port is available.

3. Linux & macOS Guide

On UNIX-based systems, scripts need executable permissions before they can be run directly.

Step 1: Clone or Navigate to the Project Directory

Open the terminal and navigate to the VistaBridge project directory.

cd /path/to/vistabridge

Step 2: Grant File Permissions

Run the following command to grant executable permissions to the setup, start, and stop scripts.

chmod +x setup.sh start.sh stop.sh

Why grant file permissions?

Downloaded or cloned .sh files may not have execute permissions by default. The chmod +x command enables the shell to execute them.

Step 3: Run the Setup Wizard

Run the setup script:

./setup.sh

Alternatively:

bash setup.sh

The Setup Wizard:

  • Validates the Node.js version.
  • Installs packages using npm install if node_modules is missing.
  • Checks whether an existing database is available.
  • Displays the current GeoServer URL and frontend port when an existing database is detected.
  • Provides options to keep existing settings, change the GeoServer URL or port, or reset the database.
  • Initializes data/geovista.db when required.
  • Saves the GeoServer URL into app_settings.
  • Generates and stores a secure 512-bit JWT secret.
  • Cleans up legacy .env files.
  • Verifies GeoServer reachability through /web/.
  • Clears any lingering process on port 3000.
  • Runs npm run build to create the optimized production build.
  • Asks whether to launch VistaBridge immediately.

Existing Database Configuration

When the Setup Wizard detects an existing database, it displays the database path, current GeoServer URL, and current frontend port.

The following options are available:

Option 1: Keep Existing Settings & Continue

  • Retains the existing GeoServer URL and frontend port.
  • Continues with the setup using the current configuration.
  • Press Enter to select this default option.

Option 2: Change GeoServer URL or Port

  • Allows users to update the GeoServer URL or frontend port.
  • The wizard prompts users to enter the required configuration values.
  • Press Enter to accept the displayed default values or enter new values.

Option 3: Reset Database

  • Starts with a fresh, empty database.
  • Existing database data may be lost when this option is selected.
  • Ensure that any required data is backed up before proceeding.

GeoServer Configuration Prompt

During configuration, the Setup Wizard displays the default GeoServer URL.

Example:

GeoServer Configuration

Default: http://localhost:8080/geoserver
Enter GeoServer URL (Press ENTER to use default):
  • Press Enter to use the displayed default URL.
  • Alternatively, enter a custom GeoServer URL, such as https://vistabridge.rottengrapes.tech/geoserver.

Frontend Port Configuration

During setup, the wizard prompts users to configure the frontend port.

Example:

Frontend Port Configuration

Enter frontend port (default 3000, press ENTER to use default):
  • Press Enter to use the default port, 3000.
  • Alternatively, enter a custom port number, such as 8081.
  • Ensure that the selected port is available before continuing.

After setup, open VistaBridge at http://localhost:<your port>. With the default configuration, the application is available at http://localhost:3000.

To change the port later, run the setup script again (./setup.sh) and enter the new port when prompted.


4. Daily Operation — Linux & macOS

Start the Application

Run the following command:

./start.sh

The start script:

  • Ensures dependencies and the production build exist.
  • Terminates any old process running on port 3000.
  • Starts the production server.
  • Opens http://localhost:3000 in the default browser.

Stop the Application

Run the following command:

./stop.sh

The stop script:

  • Finds the process running on port 3000 using available tools such as lsof, ss, or netstat.
  • Terminates the process cleanly.

Alternatively, press Ctrl+C in the running terminal.


5. Windows Guide

On Windows, the pre-configured .bat files can be run from Command Prompt, PowerShell, or by double-clicking them.

Step 1: Open the Project Folder

Navigate to the VistaBridge project folder.

vistabridge

Step 2: Run the Setup Wizard

Open PowerShell or Command Prompt in the project directory.

Run the setup script:

.\setup.bat

Alternatively, double-click setup.bat to start the Setup Wizard.

Windows SmartScreen & Permissions

If Windows SmartScreen or antivirus software displays a security prompt, review the source and allow execution only if you trust the project. Administrator rights are normally not required unless the Node.js directory is restricted.

The Windows Setup Wizard

The Setup Wizard:

  • Checks that Node.js is available in PATH.
  • Runs npm install.
  • Checks whether an existing database is available.
  • Displays the current GeoServer URL and frontend port when an existing database is detected.
  • Provides options to keep existing settings, change the GeoServer URL or port, or reset the database.
  • Initializes or updates data\geovista.db as required.
  • Saves the GeoServer configuration.
  • Generates and stores a secure 512-bit JWT secret.
  • Clears stale processes on port 3000.
  • Compiles the Next.js production bundle.
  • Asks whether to launch VistaBridge.

Existing Database Configuration

When an existing database is detected, the wizard displays the current database path, GeoServer URL, and frontend port.

Users can select one of the following options:

Option 1: Keep Existing Settings & Continue

  • Retains the current configuration.
  • Continues with setup.
  • Press Enter to select this default option.

Option 2: Change GeoServer URL or Port

  • Allows users to change the GeoServer URL or frontend port.
  • Enter the required values when prompted.
  • Press Enter to accept the displayed default values.

Option 3: Reset Database

  • Starts with a fresh, empty database.
  • Existing database data may be lost.
  • Back up any required data before selecting this option.

GeoServer Configuration Prompt

The wizard displays the default GeoServer URL.

Example:

GeoServer Configuration

Default: https://vistabridge.rottengrapes.tech/geoserver
Enter GeoServer URL (Press ENTER to use default):
  • Press Enter to use the displayed default URL.
  • Alternatively, enter a custom GeoServer URL.

Frontend Port Configuration

The wizard displays the default frontend port.

Example:

Frontend Port Configuration

Enter frontend port (default 3000, press ENTER to use default):
  • Press Enter to use port 3000.
  • Alternatively, enter a custom port number, such as 8081.
  • Ensure that the selected port is available.

After setup, open VistaBridge at http://localhost:<your port>. With the default configuration, use http://localhost:3000.


6. Daily Operation — Windows

Start the Application

Double-click start.bat or run the following command in Command Prompt or PowerShell:

.\start.bat

The start script:

  • Starts the server on port 3000.
  • Automatically opens http://localhost:3000 in the browser.

Stop the Application

Double-click stop.bat or run:

.\stop.bat

The stop script:

  • Detects the process holding port 3000 using netstat.
  • Terminates the process using taskkill /F.

Alternatively, press Ctrl+C in the Command Prompt window.


7. Script Combinations & Lifecycle Workflow

The following table provides a quick comparison of the scripts used for different operations across Windows, Linux, and macOS.

Scenario Windows Linux / macOS Description
First-time Installation setup.bat chmod +x *.sh then ./setup.sh Installs dependencies, configures the database, and builds the application.
Daily Launch start.bat ./start.sh Starts the production server and launches the browser.
Shut Down stop.bat ./stop.sh Terminates the process running on port 3000.
Switch GeoServer URL Re-run setup.bat Re-run ./setup.sh Updates the GeoServer URL in SQLite.
Change Frontend Port Re-run setup.bat Re-run ./setup.sh Allows users to configure a different frontend port.
Reset Database Select option 3 in setup.bat Select option 3 in ./setup.sh Starts with a fresh, empty database.
Rebuild After Code Edit Run setup.bat Run ./setup.sh Recompiles the production build.

8. Troubleshooting & Common Permissions Issues

Issue 1: Permission Denied When Running ./setup.sh

Fix:

Run the following command to grant executable permissions:

chmod +x setup.sh start.sh stop.sh

Issue 2: Port 3000 Is Already in Use

Use the appropriate stop script to terminate the existing process.

  • Windows: Run stop.bat.
  • Linux / macOS: Run ./stop.sh.

Issue 3: PowerShell Script Execution Policy

If PowerShell blocks script execution, run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Alternatively, run the .bat file from Command Prompt (cmd.exe).

Issue 4: GeoServer Did Not Respond Within 5 Seconds

  • Make sure GeoServer is running before setup.
  • Verify the configured GeoServer URL.
  • Check that the GeoServer /web/ endpoint responds.
  • A timeout warning does not necessarily stop setup. The URL can still be saved, and the application can connect once GeoServer becomes available.

9. Configuration & Data Notes

VistaBridge stores its application configuration in an embedded SQLite database.

The following details are stored or managed during setup:

  • Database: data/geovista.db
  • GeoServer URL: Stored in the application settings table.
  • JWT Secret: Generated during setup and stored in SQLite.
  • Legacy .env Files: Cleaned up by the setup process when applicable.

Sensitive Configuration Data

Treat the SQLite database as sensitive application configuration. Protect database backups because the database contains the JWT secret and runtime configuration.

Important: Selecting the Reset Database option starts with a fresh, empty database. Back up any required data before resetting.


10. Quick Reference

Use the following table to quickly identify the commands required for common VistaBridge operations.

Task Windows Linux / macOS
Initial Setup setup.bat chmod +x *.sh then ./setup.sh
Start start.bat ./start.sh
Stop stop.bat ./stop.sh
Production URL (Default) http://localhost:3000 http://localhost:3000
Database data\geovista.db data/geovista.db