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 100% without .env files. Configuration such as the GeoServer URL and JWT secret is stored directly inside the embedded SQLite database: data/geovista.db.

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

2. Prerequisites (All Platforms)

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

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

cd /path/to/vistabridge

Step 2: Grant File Permissions

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

Why grant file permissions?

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

Step 3: Run the Setup Wizard

./setup.sh

Alternatively:

bash setup.sh

The Setup Wizard:

  • Validates Node.js version.
  • Installs packages via npm install if node_modules is missing.
  • Prompts for the GeoServer URL.
  • Initializes data/geovista.db.
  • 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 for the optimized production build.
  • Asks whether to launch VistaBridge immediately.

GeoServer Configuration Prompt

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

Frontend Port Configuration

During setup, the wizard asks which port VistaBridge should run on.

----------------------------------------------------------------------
 Frontend Port Configuration
----------------------------------------------------------------------
Enter frontend port (default 3000, press ENTER to use default):
  • Press Enter to use the default port, 3000.
  • Or type a custom port number, for example 8081.
  • Make sure the port is free before you run setup.
  • After setup, open VistaBridge at http://localhost:<your port>. With the default, this is http://localhost:3000.
  • To change the port later, run the setup script again (setup.bat on Windows, ./setup.sh on Linux and macOS) and enter a new port when prompted.

4. Daily Operation — Linux & macOS

Start the Application

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

Stop the Application

./stop.sh
  • Finds the process on port 3000 using available tools such as lsof, ss, or netstat.
  • Terminates it 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

vistabridge

Step 2: Run the Setup Wizard

  • Double-click setup.bat.
  • Or run from CMD/PowerShell:
.\setup.bat

Windows SmartScreen & Permissions

If Windows SmartScreen or antivirus shows 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:

  • Checks that node is available in PATH.
  • Runs npm install.
  • Prompts for the GeoServer URL.
  • Writes settings to data\geovista.db.
  • Clears stale processes on port 3000.
  • Compiles the Next.js production bundle.
  • Asks whether to launch VistaBridge.

6. Daily Operation — Windows

Start the Application

  • Double-click start.bat, or run:
.\start.bat
  • Starts the server on port 3000.
  • Automatically opens http://localhost:3000.

Stop the Application

  • Double-click stop.bat, or run:
.\stop.bat
  • Detects the process holding port 3000 using netstat and terminates it using taskkill /F.
  • Alternatively, press Ctrl+C in the CMD window.

7. Script Combinations & Lifecycle Workflow

Scenario Windows Linux / macOS Description
First-time Installation setup.bat chmod +x *.sh then ./setup.sh Install dependencies, configure DB, and build.
Daily Launch start.bat ./start.sh Start production server and launch browser.
Shut Down stop.bat ./stop.sh Terminate process on port 3000.
Switch GeoServer URL Re-run setup.bat Re-run ./setup.sh Update the URL in SQLite.
Rebuild After Code Edit Run setup.bat Run ./setup.sh Recompile the production build.

8. Troubleshooting & Common Permissions Issues

Issue 1: Permission denied when running ./setup.sh

Fix:

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

Issue 2: Port 3000 is already in use

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

Issue 3: PowerShell Script Execution Policy

If PowerShell blocks scripts:

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

  • 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 setup when applicable.

Sensitive Configuration Data

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

10. Quick Reference

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 http://localhost:3000 http://localhost:3000
Database data\geovista.db data/geovista.db