chore: auto-start Redis and handle port collisions (#581)

Author: FelixTJDietrich

README.md

@@ -18,17 +18,18 @@ npm install
 # Build all packages
 npm run build
 
-# Start Redis (requires Docker)
-npm run start:localdb
-
 # Start dev stack with hot reload
 npm run dev
 ```
 
 This starts:
 - **Library** build watch (auto-rebuilds on changes)
-- **Server** (tsx watch) on http://localhost:8000 with WebSocket relay on ws://localhost:4444
-- **Webapp** (Vite HMR) on http://localhost:5173
+- **Server** (tsx watch) on a printed local HTTP port with a matching WebSocket relay port
+- **Webapp** (Vite HMR) on a printed local dev URL
+
+`npm run dev` also handles local port collisions for the webapp, server, WebSocket relay, and Redis. It reuses an existing local Redis when possible and otherwise starts the local Redis container on a free host port. Docker still needs to be available when no compatible local Redis is already running.
+
+If you need to pin preferred ports, set `APOLLON_WEBAPP_PORT`, `APOLLON_SERVER_PORT`, `APOLLON_WS_PORT`, or `APOLLON_REDIS_PORT` before running `npm run dev`.
 
 No `.env` files needed — defaults match the local setup.
 
@@ -58,7 +59,7 @@ For complete documentation, setup instructions, and guides, visit:
 
 - **Node.js** (version specified in `.nvmrc`)
 - **npm** 7+ (for workspace support)
-- **Docker** (for running Redis locally)
+- **Docker** (for running Redis locally via `npm run dev` or `npm run start:localdb`)
 
 ## Contributing
 

docker/compose.local.db.yml

@@ -2,7 +2,7 @@ services:
   db:
     image: redis:7-alpine
     ports:
-      - "6379:6379"
+      - "${REDIS_PORT:-6379}:6379"
     volumes:
       - dbdata:/data
 

docs/development/scripts.md

@@ -22,7 +22,8 @@ Here are the commonly used scripts defined in the monorepo:
   ```bash
   npm run dev
   ```
-  Starts the library (build watch), server (tsx watch on http://localhost:8000), and webapp (Vite HMR on http://localhost:5173) concurrently.
+  Starts the library (build watch), server, and webapp concurrently. The command also resolves local port collisions for the webapp, server, WebSocket relay, and Redis, and it starts the local Redis container only when no compatible local Redis instance is already reachable.
+  You can prefer custom ports by setting `APOLLON_WEBAPP_PORT`, `APOLLON_SERVER_PORT`, `APOLLON_WS_PORT`, or `APOLLON_REDIS_PORT` before starting the stack.
 
 - **Start production build:**
   ```bash

docs/getting-started/setup.md

@@ -30,18 +30,12 @@ Follow these steps to set up the Apollon monorepo on your local machine.
    npm run build
    ```
 
-5. **Start Redis** (requires Docker):
-
-   ```bash
-   npm run start:localdb
-   ```
-
-6. **Start development with hot reload:**
+5. **Start development with hot reload** (requires Docker for Redis):
 
    ```bash
    npm run dev
    ```
 
-   This starts the library (build watch), server (http://localhost:8000), and webapp (http://localhost:5173) with hot reload.
+   This starts the library (build watch), server, webapp, and the local Redis dependency used by the server. If the default local ports are already in use, the command selects free ports automatically and prints the chosen URLs in the terminal output.
 
 No `.env` files are needed — all defaults match the local setup. See `standalone/server/.env.example` and `standalone/webapp/.env.example` if you need to override defaults.

package.json

@@ -14,16 +14,18 @@
     "build:server": "npm run build --workspace=@tumaet/server",
     "build:webapp": "npm run build --workspace=@tumaet/webapp",
     "build:vscode": "npm run build:all --workspace=apollon-vscode",
-    "dev": "concurrently -n lib,server,webapp -c yellow,blue,magenta \"npm run dev:lib\" \"npm run dev:server\" \"npm run dev:webapp\"",
+    "dev": "node scripts/dev.mjs",
     "dev:lib": "npm run build:watch --workspace=@tumaet/apollon",
-    "dev:server": "npm run dev --workspace=@tumaet/server",
+    "dev:server": "npm run ensure:localdb && npm run dev --workspace=@tumaet/server",
     "dev:webapp": "npm run start --workspace=@tumaet/webapp",
     "dev:vscode": "npm run watch --workspace=apollon-vscode",
     "start": "concurrently \"npm run start:server\" \"npm run start:webapp\"",
     "start:server": "npm run start --workspace=@tumaet/server",
     "start:webapp": "npm run start --workspace=@tumaet/webapp",
     "start:webapp:host": "npm run start:host --workspace=@tumaet/webapp",
     "start:localdb": "docker compose -f docker/compose.local.db.yml up -d",
+    "wait:localdb": "node scripts/wait-for-redis.mjs",
+    "ensure:localdb": "npm run start:localdb && npm run wait:localdb",
     "lint": "concurrently \"npm run lint:lib\" \"npm run lint:server\" \"npm run lint:webapp\"",
     "lint:lib": "npm run lint --workspace=@tumaet/apollon",
     "lint:server": "npm run lint --workspace=@tumaet/server",