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 port3000, starts the server, and launches the browser. - Stop (
stop.bat/stop.sh): Locates and terminates the background server process using port3000.
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/geoserverhttps://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.
Step 2: Grant File Permissions¶
Run the following command to grant executable permissions to the setup, start, and stop scripts.
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:
Alternatively:
The Setup Wizard:
- Validates the Node.js version.
- Installs packages using
npm installifnode_modulesis 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.dbwhen required. - Saves the GeoServer URL into
app_settings. - Generates and stores a secure 512-bit JWT secret.
- Cleans up legacy
.envfiles. - Verifies GeoServer reachability through
/web/. - Clears any lingering process on port
3000. - Runs
npm run buildto 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:
- 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:
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:3000in the default browser.
Stop the Application¶
Run the following command:
The stop script:
- Finds the process running on port
3000using available tools such aslsof,ss, ornetstat. - 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.
Step 2: Run the Setup Wizard¶
Open PowerShell or Command Prompt in the project directory.
Run the setup script:
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.dbas 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:
- 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:
The start script:
- Starts the server on port
3000. - Automatically opens
http://localhost:3000in the browser.
Stop the Application¶
Double-click stop.bat or run:
The stop script:
- Detects the process holding port
3000usingnetstat. - 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:
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:
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
.envFiles: 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 |