iPuzzle/instructions.md

iPuzzle Setup Instructions

This guide covers how to set up and run the iPuzzle multiplayer puzzle game on both Windows and Linux.

Prerequisites

Node.js

The server requires Node.js (version 18 or later).

Windows:

1. Download the installer from https://nodejs.org/ (LTS version recommended)
2. Run the installer — accept defaults, ensure "Add to PATH" is checked
3. Open a new Command Prompt or PowerShell and verify:

   node --version
   npm --version
   

Linux (Ubuntu/Debian):

sudo apt update
sudo apt install nodejs npm
node --version
npm --version

Linux (via nvm — recommended for version management):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# Restart your terminal, then:
nvm install --lts
node --version

Installation

1. Clone or copy the project to your machine.

2. Install server dependencies:

   Windows (Command Prompt or PowerShell):

   cd server
   npm install
   cd ..
   

   Linux:

   cd server
   npm install
   cd ..
   

   This installs the ws WebSocket library — the only dependency.

Running the Server

The server serves both the game files and WebSocket connections on a single port (default 8080).

Windows:

node server\server.js

Linux:

node server/server.js

You should see:

iPuzzle server running on http://localhost:8080

Open http://localhost:8080 in your browser to play.

Changing the Port

Set the PORT environment variable:

Windows (Command Prompt):

set PORT=3000
node server\server.js

Windows (PowerShell):

$env:PORT=3000
node server\server.js

Linux:

PORT=3000 node server/server.js

Playing the Game

Single Player

1. Open http://localhost:8080
2. Click "New Puzzle"
3. Select an image and piece count, then click "Start"

Multiplayer

1. Player A opens the game and creates a new puzzle
2. Player A shares the 4-character room code shown on screen
3. Player B opens the game and clicks "Join Puzzle"
4. Player B enters the room code and clicks "Join"
5. Both players can now move pieces in real time

Each player controls their own camera zoom (scroll wheel) and pan (drag empty space).

Hosting for Remote Players

To make the game accessible beyond localhost, you need to expose the Node server to the internet. There are two common approaches:

Option A: Direct Access (No TLS)

If your machine has a public IP or you're on a LAN:

1. Run the server on your desired port
2. Open that port in your firewall
3. Players connect via http://YOUR_IP:PORT

Windows Firewall (run as Administrator):

netsh advfirewall firewall add rule name="iPuzzle" dir=in action=allow protocol=TCP localport=8080

Linux (ufw):

sudo ufw allow 8080/tcp

Option B: Reverse Proxy with TLS (Recommended for Production)

For hosting at a domain like https://ipuzzle.example.com, put a reverse proxy in front of the Node server. The proxy terminates TLS and forwards both HTTP and WebSocket traffic to the Node server.

Key requirement: Your reverse proxy must support WebSocket upgrades. Both nginx and Caddy handle this.

Example nginx config:

server {
    listen 443 ssl;
    server_name ipuzzle.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Example Caddy config (auto-TLS):

ipuzzle.example.com {
    reverse_proxy 127.0.0.1:8080
}

Caddy automatically obtains and renews TLS certificates from Let's Encrypt.

Running as a Background Service

Windows (Task Scheduler)

1. Open Task Scheduler
2. Create Basic Task > name it "iPuzzle Server"
3. Trigger: "When the computer starts"
4. Action: "Start a program"
   • Program: node
   • Arguments: server\server.js
   • Start in: C:\path\to\iPuzzle
5. Check "Run whether user is logged on or not"

Windows (NSSM — recommended)

NSSM (Non-Sucking Service Manager) wraps Node as a proper Windows service:

1. Download from https://nssm.cc/download
2. Run:

   nssm install iPuzzle "C:\Program Files\nodejs\node.exe" "C:\path\to\iPuzzle\server\server.js"
   nssm set iPuzzle AppDirectory "C:\path\to\iPuzzle"
   nssm start iPuzzle
   

Linux (systemd)

Create /etc/systemd/system/ipuzzle.service:

[Unit]
Description=iPuzzle Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/path/to/iPuzzle
ExecStart=/usr/bin/node server/server.js
Restart=on-failure
Environment=PORT=8080

[Install]
WantedBy=multi-user.target

Then:

sudo systemctl daemon-reload
sudo systemctl enable ipuzzle
sudo systemctl start ipuzzle
sudo systemctl status ipuzzle

Troubleshooting

"EADDRINUSE" error on startup: Another process is using the port. Either stop that process or use a different port:

# Find what's using port 8080:
# Windows:  netstat -ano | findstr :8080
# Linux:    lsof -i :8080

# Or just use a different port:
# PORT=3000 node server/server.js

WebSocket connection fails in browser:

• Make sure you're accessing the game through the Node server (not a separate Python/static file server)
• If behind a reverse proxy, ensure WebSocket upgrade headers are forwarded (see nginx/Caddy examples above)
• Check browser console for the exact WebSocket URL — it should match your server's address

Pieces don't move for other players:

• Both players must be connected to the same server
• Check the connection status indicator (bottom of puzzle screen) — it should say "Connected"
• If it says "Disconnected", the WebSocket connection was lost

Room not found when joining:

• Room codes are case-sensitive (always uppercase)
• Rooms are deleted 5 minutes after the last player leaves
• The room must be created before another player can join