CruiseBuddy v1


QUICK START — WINDOWS VPS

1. Install Python 3.10 or newer

If Python is not already installed:

[https://python.org](https://python.org)

During installation, make sure "Add Python to PATH" is checked.

2. Install the required dependency

Open Command Prompt or PowerShell and run:

pip install aiohttp

3. Copy the files to your VPS

Place the following files in the same folder. For example:

C:\CruiseBuddy\

The folder should contain:

server.py
index.html
requirements.txt

4. Start the server

Open Command Prompt or PowerShell and run:

cd C:\CruiseBuddy
python server.py

5. Open CruiseBuddy in a browser

On the VPS itself:

[http://localhost:8765](http://localhost:8765)

From another device on the same network:

http://YOUR_VPS_IP:8765

If other devices cannot connect, make sure TCP port 8765 is allowed through Windows Firewall.

WINDOWS FIREWALL

To allow external connections to CruiseBuddy, run the following command as Administrator:

netsh advfirewall firewall add rule name="CruiseBuddy" dir=in action=allow protocol=TCP localport=8765

RUNNING CRUISEBUDDY IN THE BACKGROUND

To keep the server running after closing the terminal, run:

start /B python server.py > cruisebuddy.log 2>&1

Alternatively, NSSM (Non-Sucking Service Manager) can be used to install CruiseBuddy as a Windows Service.

LINUX MIGRATION

The same basic setup can be used on Linux.

Install the dependency:

pip install aiohttp

Start the server:

python3 server.py

Alternatively, PM2 can be used to keep the server running:

pm2 start server.py --interpreter python3 --name cruisebuddy

ARCHITECTURE

Frontend:
A single HTML file using Leaflet.js for the map, CartoDB Dark Matter map tiles, a WebSocket client for real-time communication, and the browser's GPS Geolocation API.

Backend:
A Python aiohttp server responsible for WebSocket connections, room management, position updates, and group chat.

Communication:
The frontend and backend communicate using JSON over WebSocket. Participant positions are sent approximately every 2 seconds while a drive is active.

FEATURES

* The leader creates a room using a 5-digit room code.
* The leader sets the maximum number of participants, from 2 to 10.
* Members join a room using the room code.
* Participants can see the current participant list.
* The leader can start, pause, resume, and end the drive.
* Real-time GPS tracking displays participant locations.
* A blue line connects followers to the leader during an active drive.
* The tracking line turns red when the drive is paused.
* Group chat is available during the session.
* Screen Wake Lock prevents supported phones from going to sleep during the drive.
* The application automatically attempts to reconnect if the connection is lost.
* No accounts are required.
* No user data is permanently stored. Room and participant data are ephemeral.

HOST AND PORT CONFIGURATION

The server's host and port can be changed at the top of server.py:

HOST = "0.0.0.0"
PORT = 8765

HOST = "0.0.0.0" means the server listens for connections on all network interfaces.

PORT = 8765 is the port used by CruiseBuddy. Change this value if another application is already using port 8765.