fix: use uncommon default blue-green port

Author: devalade

README.md

@@ -468,7 +468,7 @@ export default shipnode
 
 Backends with a domain and a PM2 web port use blue-green releases automatically. Shipnode starts the new web process on the idle port, checks it, and reloads Caddy only after it is healthy. Apps without a domain and worker-only apps keep the PM2 recreate path. Use `.noZeroDowntime()` to opt out explicitly; raw configuration may set `zeroDowntime: false`.
 
-Blue-green keeps the previous and current web processes resident, so budget about **2× the web process memory**. On an eligible Caddy backend, `.zeroDowntime(altPort?)` remains available to force the mode and choose the alternate port (default: web port + 1).
+Blue-green keeps the previous and current web processes resident, so budget about **2× the web process memory**. On an eligible Caddy backend, `.zeroDowntime(altPort?)` remains available to force the mode and choose the alternate port. By default, Shipnode uses a less commonly occupied port offset by 10,000 (`3000 → 13000`); near the top of the TCP range it subtracts 10,000 instead.
 
 Every app still uses a Capistrano-style release structure:
 

docs/adr/0005-blue-green-zero-downtime.md

@@ -4,7 +4,7 @@ Backend web apps behind Caddy (a domain plus a PM2 web port) use blue-green rele
 
 ## Mechanism
 
-Two ports, named **blue** and **green**. Blue is the web app's configured `port`; green is `altPort` (default `port + 1`). Exactly one colour is *active* at a time — Caddy's `reverse_proxy` upstream points at it. The active colour and the port pair are persisted on the host in `<appPath>/.shipnode/deploy-state.json`.
+Two ports, named **blue** and **green**. Blue is the web app's configured `port`; green is `altPort`. By default, green uses a less commonly occupied port offset by 10,000 (`3000 → 13000`); for blue ports above 55535, Shipnode subtracts 10,000 to remain within the TCP port range. Exactly one colour is *active* at a time — Caddy's `reverse_proxy` upstream points at it. The active colour and the port pair are persisted on the host in `<appPath>/.shipnode/deploy-state.json`.
 
 Each deploy:
 

src/config/builder.ts

@@ -134,7 +134,7 @@ export class ShipnodeBuilder {
 
   /**
    * Enable zero-downtime (blue-green) releases for the web app. Optional
-   * `altPort` sets the green port (defaults to web port + 1).
+   * `altPort` sets the green port (defaults to an uncommon port offset by 10,000).
    */
   zeroDowntime(altPort?: number): this {
     this.config.zeroDowntime = true;
@@ -363,7 +363,7 @@ export class ShipnodeAppBuilder {
 
   /**
    * Enable zero-downtime (blue-green) releases for this web app. Optional
-   * `altPort` sets the green port (defaults to web port + 1).
+   * `altPort` sets the green port (defaults to an uncommon port offset by 10,000).
    */
   zeroDowntime(altPort?: number): this {
     this.state.zeroDowntime = true;

src/domain/deploy/blue-green.ts

@@ -44,9 +44,20 @@ export function portFor(color: DeployColor, state: DeployState): number {
   return color === 'blue' ? state.bluePort : state.greenPort;
 }
 
-/** The green port: explicit `altPort`, else web port + 1. */
+const ALT_PORT_OFFSET = 10_000;
+const MAX_TCP_PORT = 65_535;
+
+/**
+ * Resolve the green port.
+ *
+ * An explicit `altPort` wins. Otherwise the default is 10,000 above the web
+ * port, or 10,000 below it near the top of the TCP port range.
+ */
 export function resolveAltPort(webPort: number, altPort?: number): number {
-  return altPort ?? webPort + 1;
+  if (altPort !== undefined) return altPort;
+  return webPort <= MAX_TCP_PORT - ALT_PORT_OFFSET
+    ? webPort + ALT_PORT_OFFSET
+    : webPort - ALT_PORT_OFFSET;
 }
 
 /** PM2 process name for the web app of a given colour (`api-blue`, `api-green`). */

src/shared/types.ts

@@ -170,8 +170,8 @@ export interface ShipnodeApp {
   zeroDowntime: boolean;
   /**
    * The second port used by blue-green. Blue = the web app's port, green =
-   * `altPort` (defaults to web port + 1). Both colours may be resident at once,
-   * so this port must be free on the host.
+   * `altPort` (defaults to an uncommon port offset by 10,000). Both colours may
+   * be resident at once, so this port must be free on the host.
    */
   altPort?: number;
   sharedDirs?: string[];

tests/unit/blue-green-orchestrator.test.ts

@@ -72,13 +72,13 @@ describe('blue-green deploy (orchestrator)', () => {
     const webEco = cmds.find((c) => c.includes('ecosystem.web.config.cjs') && c.includes('echo'));
     expect(webEco).toBeDefined();
     expect(webEco).toContain('app-green');
-    expect(webEco).toContain('PORT: 3001');
+    expect(webEco).toContain('PORT: 13000');
 
-    const curl = cmds.find((c) => c.includes('curl') && c.includes('localhost:3001/health'));
+    const curl = cmds.find((c) => c.includes('curl') && c.includes('localhost:13000/health'));
     expect(curl).toBeDefined();
 
-    // Caddy flipped to port 3000 and reloaded, then state persisted — in that order
-    const caddyIdx = cmds.findIndex((c) => c.includes('reverse_proxy localhost:3001') && c.includes('tee'));
+    // Caddy flipped to the green port and reloaded, then state persisted — in that order
+    const caddyIdx = cmds.findIndex((c) => c.includes('reverse_proxy localhost:13000') && c.includes('tee'));
     const reloadIdx = cmds.findIndex((c) => c.includes('systemctl reload caddy'));
     const stateIdx = cmds.findIndex((c) => c.includes('deploy-state.json') && c.includes('base64 -d'));
     const cleanupIdx = cmds.findIndex((c) => c.includes('pm2 delete "app"'));

tests/unit/blue-green.test.ts

@@ -23,11 +23,15 @@ describe('blue-green helpers', () => {
     expect(portFor('green', state)).toBe(3001);
   });
 
-  it('resolveAltPort defaults to web port + 1', () => {
-    expect(resolveAltPort(3000)).toBe(3001);
+  it('resolveAltPort defaults to an uncommon port 10,000 above the web port', () => {
+    expect(resolveAltPort(3000)).toBe(13000);
     expect(resolveAltPort(3000, 4000)).toBe(4000);
   });
 
+  it('resolveAltPort stays within the valid TCP port range', () => {
+    expect(resolveAltPort(60_000)).toBe(50_000);
+  });
+
   it('coloredWebName suffixes the pm2 name', () => {
     // web app name equals namespace -> unprefixed, then coloured
     expect(coloredWebName('api', 'api', 'blue')).toBe('api-blue');

tests/unit/multi-app-orchestrator.test.ts

@@ -32,7 +32,7 @@ describe('DeployOrchestrator — multi-app', () => {
       // lock
       .when((cmd) => cmd.includes('deploy.lock'), { stdout: 'OK', exitCode: 0 })
       // health check on the backend
-      .when((cmd) => cmd.includes('curl') && cmd.includes('localhost:3001'), { stdout: '200 42', exitCode: 0 })
+      .when((cmd) => cmd.includes('curl') && cmd.includes('localhost:13000'), { stdout: '200 42', exitCode: 0 })
       // pm2 jlist — both apps must be online
       .when((cmd) => cmd.includes('pm2 jlist'), {
         stdout: JSON.stringify([
@@ -96,7 +96,7 @@ describe('DeployOrchestrator — multi-app', () => {
     expect(webMkdir.length).toBeGreaterThan(0);
 
     // Health check ran for the backend (frontend has none)
-    const health = history.filter((h) => h.command.includes('curl') && h.command.includes('localhost:3001'));
+    const health = history.filter((h) => h.command.includes('curl') && h.command.includes('localhost:13000'));
     expect(health.length).toBeGreaterThan(0);
   });
 });

website/src/content/docs/docs/configuration.md

@@ -123,7 +123,7 @@ Registry passwords are read from environment variables on the remote host. If `R
 | `.postDeploy(fn)` | Run a function on the server after a healthy release. |
 | `.build()` | Required terminal call. Returns the resolved config. |
 
-Backend apps with both `.domain(...)` and a PM2 web `.port(...)` use blue-green deploys by default. They temporarily need about 2× the web process memory while both colours are resident. Backends without a domain and worker-only apps use PM2 recreate. Raw configs can opt out with `zeroDowntime: false`.
+Backend apps with both `.domain(...)` and a PM2 web `.port(...)` use blue-green deploys by default. The alternate port defaults to a less commonly occupied value offset by 10,000 (`3000 → 13000`), with a subtraction near the top of the TCP range. They temporarily need about 2× the web process memory while both colours are resident. Backends without a domain and worker-only apps use PM2 recreate. Raw configs can opt out with `zeroDowntime: false`.
 
 ## Aliases