Align dev ports to 4000-range

Author: gildesmarais

.devcontainer/Dockerfile

@@ -29,6 +29,6 @@ ENV BUNDLE_PATH=/usr/local/bundle
 
 USER "$USER"
 
-EXPOSE 3000
+EXPOSE 4000
 
 CMD ["sleep", "infinity"]

.devcontainer/README.md

@@ -7,8 +7,8 @@ Containers extension) or GitHub Codespaces and use that environment for all work
 
 The devcontainer starts one service named `app` and exposes:
 
-- **Port 3001:** Ruby app (forwarded from container port 3000)
-- **Port 4321:** Astro dev server
+- **Port 4000:** Ruby app
+- **Port 4001:** Astro dev server
 
 The repo is mounted at `/workspace`. Bundler gems are cached in a Docker volume to speed up
 future launches.

.devcontainer/devcontainer.json

@@ -27,13 +27,13 @@
       }
     }
   },
-  "forwardPorts": [3001, 4321],
+  "forwardPorts": [4000, 4001],
   "portsAttributes": {
-    "3001": {
+    "4000": {
       "label": "Ruby App",
       "onAutoForward": "notify"
     },
-    "4321": {
+    "4001": {
       "label": "Astro Dev Server",
       "onAutoForward": "silent"
     }

.devcontainer/docker-compose.yml

@@ -9,10 +9,11 @@ services:
       - ../:/workspace:cached
       - bundle-cache:/usr/local/bundle
     ports:
-      - "3001:3000"
+      - "4000:4000"
     environment:
       - RACK_ENV=development
       - BUNDLE_PATH=/usr/local/bundle
+      - PORT=4000
     command: sleep infinity
     user: vscode
     working_dir: /workspace

README.md

@@ -45,15 +45,13 @@ curl -X POST "https://your-domain.com/api/v1/feeds" \
 2. Set `HTML2RSS_SECRET_KEY` in `docker-compose.yml`.
 3. Start: `docker-compose up`.
 
-UI + API run on `http://localhost:3000`. The app exits if the secret key is missing.
+UI + API run on `http://localhost:4000`. The app exits if the secret key is missing.
 
-## Development (Dev Container only)
-We support a single, batteries-included workflow based on the repository's
-[Dev Container](.devcontainer/README.md). Always work inside the Dev Container locally or in
-GitHub Codespaces—running the app directly on the host is no longer documented or supported.
-All agents and automation must run inside the Dev Container as well.
+## Development (Dev Container)
+Use the repository's [Dev Container](.devcontainer/README.md) for all local development and tests.
+Running the app directly on the host is not supported.
 
-Inside the Dev Container, use:
+Quick start inside the Dev Container:
 
 ```
 make setup
@@ -64,37 +62,29 @@ bundle exec rubocop -F
 bundle exec rspec
 ```
 
-Dev Container app URL: `http://localhost:3001`.
-
-## Frontend Development
-```
-cd frontend
-npm install
-npm run dev
-```
-The Ruby server continues to serve the production build while Astro runs with hot reload on port 4321.
+Dev URLs: Ruby app at `http://localhost:4000`, Astro dev server at `http://localhost:4001`.
 
 ## Make Targets
 
 | Command              | Purpose                                                 |
 | -------------------- | ------------------------------------------------------- |
 | `make help`          | List available shortcuts.                               |
 | `make setup`         | Install Ruby and Node dependencies.                     |
-| `make dev`           | Run Ruby (port 3000) and Astro (port 4321) dev servers. |
+| `make dev`           | Run Ruby (port 4000) and Astro (port 4001) dev servers. |
 | `make dev-ruby`      | Start only the Ruby server.                             |
-| `make dev-frontend`  | Start only the Astro dev server.                        |
+| `make dev-frontend`  | Start only the Astro dev server (port 4001).            |
 | `make test`          | Run Ruby and frontend test suites.                      |
 | `make test-ruby`     | Run Ruby specs.                                         |
 | `make test-frontend` | Run frontend unit and contract tests.                   |
 | `make lint`          | Run all linters.                                        |
 | `make lintfix`       | Auto-fix lint warnings where possible.                  |
 | `make clean`         | Remove build artefacts.                                 |
 
-## Frontend npm Scripts
+## Frontend npm Scripts (inside Dev Container)
 
 | Command                 | Purpose                           |
 | ----------------------- | --------------------------------- |
-| `npm run dev`           | Astro dev server with hot reload. |
+| `npm run dev`           | Astro dev server with hot reload (port 4001). |
 | `npm run build`         | Production build.                 |
 | `npm run test:run`      | Unit tests (Vitest).              |
 | `npm run test:contract` | Contract tests with MSW.          |

bin/dev

@@ -31,7 +31,7 @@ cleanup() {
 
   # Clean up any remaining processes on our ports
   pkill -f "puma.*html2rss-web" 2>/dev/null || true
-  pkill -f "astro.*dev.*3001" 2>/dev/null || true
+  pkill -f "astro.*dev.*4001" 2>/dev/null || true
 
   echo "✅ Development servers stopped"
   exit 0
@@ -40,18 +40,18 @@ cleanup() {
 trap cleanup SIGINT SIGTERM
 
 # Prevent silent failures from port conflicts
-if lsof -Pi :3000 -sTCP:LISTEN -t >/dev/null 2>&1; then
-  echo "❌ Port 3000 is already in use. Run: \`pkill -f 'puma.*html2rss-web'\`"
+if lsof -Pi :4000 -sTCP:LISTEN -t >/dev/null 2>&1; then
+  echo "❌ Port 4000 is already in use. Run: \`pkill -f 'puma.*html2rss-web'\`"
   exit 1
 fi
 
 # Start Ruby server
-bundle exec puma -p 3000 -C config/puma.rb &
+bundle exec puma -p 4000 -C config/puma.rb &
 RUBY_PID=$!
 
 # Verify Ruby server started successfully
 sleep 3
-if ! kill -0 $RUBY_PID 2>/dev/null || ! lsof -Pi :3000 -sTCP:LISTEN -t >/dev/null 2>&1; then
+if ! kill -0 $RUBY_PID 2>/dev/null || ! lsof -Pi :4000 -sTCP:LISTEN -t >/dev/null 2>&1; then
   echo "❌ Ruby server failed to start"
   exit 1
 fi
@@ -69,5 +69,5 @@ if ! kill -0 $ASTRO_PID 2>/dev/null; then
   exit 1
 fi
 
-echo "✅ Development environment ready at http://localhost:3001"
+echo "✅ Development environment ready at http://localhost:4001"
 wait $RUBY_PID $ASTRO_PID

bin/dev-ruby

@@ -11,10 +11,10 @@ fi
 export RACK_ENV=${RACK_ENV:-development}
 
 # Prevent silent failures from port conflicts
-if lsof -Pi :${PORT:-3000} -sTCP:LISTEN -t >/dev/null 2>&1; then
-  echo "❌ Port ${PORT:-3000} is already in use. Run: pkill -f 'puma.*html2rss-web'"
+if lsof -Pi :${PORT:-4000} -sTCP:LISTEN -t >/dev/null 2>&1; then
+  echo "❌ Port ${PORT:-4000} is already in use. Run: pkill -f 'puma.*html2rss-web'"
   exit 1
 fi
 
 echo "Starting Ruby server (code reloading enabled)"
-bundle exec puma -p ${PORT:-3000} -C config/puma.rb
+bundle exec puma -p ${PORT:-4000} -C config/puma.rb

bin/dev-with-frontend

@@ -14,9 +14,9 @@ export RACK_ENV=${RACK_ENV:-development}
 
 echo "Starting html2rss-web development environment..."
 echo "Environment: $RACK_ENV"
-echo "Ruby server: http://localhost:3000"
-echo "Astro dev server: http://localhost:4321 (with live reload)"
-echo "Main development URL: http://localhost:4321"
+echo "Ruby server: http://localhost:4000"
+echo "Astro dev server: http://localhost:4001 (with live reload)"
+echo "Main development URL: http://localhost:4001"
 echo ""
 
 # Function to cleanup background processes
@@ -38,7 +38,7 @@ trap cleanup SIGINT SIGTERM
 
 # Start Ruby server in background
 echo "Starting Ruby server..."
-bundle exec puma -p ${PORT:-3000} -C config/puma.rb &
+bundle exec puma -p ${PORT:-4000} -C config/puma.rb &
 RUBY_PID=$!
 
 # Wait a moment for Ruby server to start

docker-compose.yml

@@ -6,17 +6,18 @@ services:
     image: gilcreator/html2rss-web
     restart: unless-stopped
     ports:
-      - "127.0.0.1:3000:3000"
+      - "127.0.0.1:4000:4000"
     volumes:
       - type: bind
         source: ./config/feeds.yml
         target: /app/config/feeds.yml
         read_only: true
     environment:
       RACK_ENV: production
+      PORT: 4000
       HTML2RSS_SECRET_KEY: your-generated-secret-key-here
       HEALTH_CHECK_TOKEN: health-check-token-xyz789
-      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:3001
+      BROWSERLESS_IO_WEBSOCKET_URL: ws://browserless:4002
       BROWSERLESS_IO_API_TOKEN: 6R0W53R135510
 
   watchtower:
@@ -30,7 +31,9 @@ services:
   browserless:
     image: "ghcr.io/browserless/chromium"
     restart: unless-stopped
+    ports:
+      - "127.0.0.1:4002:4002"
     environment:
-      PORT: 3001
+      PORT: 4002
       CONCURRENT: 10
       TOKEN: 6R0W53R135510

frontend/astro.config.mjs

@@ -5,14 +5,14 @@ import preact from "@astrojs/preact";
 export default defineConfig({
   output: "static",
   server: {
-    port: 3001,
+    port: 4001,
     host: true,
   },
   vite: {
     server: {
       proxy: {
-        "/api": "http://localhost:3000",
-        "/rss.xsl": "http://localhost:3000",
+        "/api": "http://localhost:4000",
+        "/rss.xsl": "http://localhost:4000",
       },
     },
   },