fix: bind to 0.0.0.0 and prefer PORT over APP_PORT for platform deploys

The Express and H3 drivers now read APP_HOST (falling back to HOST),
defaulting to 0.0.0.0 so the server listens on all network interfaces.
This lets platform healthcheck proxies such as Railway reach the app
instead of failing against a localhost-only bind.

Server port resolution also now prefers the platform-provided PORT env
variable over APP_PORT (PORT -> APP_PORT -> 3000), so deployments bind to
the expected port without extra configuration.

Adds APP_HOST to the Express/H3 .env templates and documents host/port
binding (with Railway guidance) in the runtime guides.

Author: exronnin

docs/guide/express-runtime.md

@@ -121,6 +121,22 @@ this.driver = new ExpressDriver({
 });
 ```
 
+## Host & Port Binding
+
+The server resolves its listening port and host from environment variables, which makes it portable across hosting platforms (Railway, Heroku, Render, etc.).
+
+| Variable               | Default   | Purpose                                                         |
+| ---------------------- | --------- | --------------------------------------------------------------- |
+| `PORT`                 | —         | Platform-provided port. Preferred over `APP_PORT` when present. |
+| `APP_PORT`             | `3000`    | Application port used when `PORT` is not set.                   |
+| `APP_HOST` (or `HOST`) | `0.0.0.0` | Host the server binds to.                                       |
+
+Port resolution order is `PORT` → `APP_PORT` → `3000`. Platforms such as Railway inject a `PORT` variable at runtime, so it takes precedence automatically.
+
+The server binds to `0.0.0.0` by default so it is reachable on all network interfaces. This is required for platform healthcheck proxies (e.g. Railway) to reach the app. To restrict the server to local connections only, set `APP_HOST=localhost`.
+
+> **Deploying to Railway:** point `APP_PORT` at Railway's `PORT` variable (`APP_PORT=${{ PORT }}`) or simply rely on the built-in `PORT` precedence, and leave `APP_HOST` at its `0.0.0.0` default.
+
 ## Notes
 
 - `app.boot(port)` mounts public assets, binds router, applies middleware, registers error handling, starts the server, and attaches graceful shutdown.

docs/guide/h3-runtime.md

@@ -118,6 +118,22 @@ this.driver = new H3Driver({
 });
 ```
 
+## Host & Port Binding
+
+The server resolves its listening port and host from environment variables, which makes it portable across hosting platforms (Railway, Heroku, Render, etc.).
+
+| Variable               | Default   | Purpose                                                         |
+| ---------------------- | --------- | --------------------------------------------------------------- |
+| `PORT`                 | —         | Platform-provided port. Preferred over `APP_PORT` when present. |
+| `APP_PORT`             | `3000`    | Application port used when `PORT` is not set.                   |
+| `APP_HOST` (or `HOST`) | `0.0.0.0` | Host the server binds to.                                       |
+
+Port resolution order is `PORT` → `APP_PORT` → `3000`. Platforms such as Railway inject a `PORT` variable at runtime, so it takes precedence automatically.
+
+The server binds to `0.0.0.0` by default so it is reachable on all network interfaces. This is required for platform healthcheck proxies (e.g. Railway) to reach the app. To restrict the server to local connections only, set `APP_HOST=localhost`.
+
+> **Deploying to Railway:** point `APP_PORT` at Railway's `PORT` variable (`APP_PORT=${{ PORT }}`) or simply rely on the built-in `PORT` precedence, and leave `APP_HOST` at its `0.0.0.0` default.
+
 ## Notes
 
 - `app.boot(port)` mounts public assets, binds router, applies middleware, starts the server, and attaches graceful shutdown.

docs/more/changelog.md

@@ -8,12 +8,20 @@ The format follows semantic versioning principles.
 
 ### Added
 
+- Added `APP_HOST` (with `HOST` fallback) to override the server bind host in the Express and H3 drivers, defaulting to `0.0.0.0` so the app is reachable on all network interfaces.
+
 ### Changed
 
+- Prefer the platform-provided `PORT` env variable over `APP_PORT` when resolving the server port, so deployments on Railway, Heroku, and similar platforms bind to the expected port automatically.
+
 ### Docs
 
+- Documented host and port binding for the Express and H3 runtimes, including Railway deployment guidance.
+
 ### Fixed
 
+- Fixed deployments where the server bound to `localhost` and platform healthcheck proxies (e.g. Railway) could not reach the app.
+
 ## [0.4.0] - 2026-05-07
 
 ### Added

packages/contract/src/Arkstack.ts

@@ -53,14 +53,15 @@ export abstract class Arkstack<TApp, TRoutes = unknown, THandler = unknown> {
     /**
      * Boostrap the app and start up the server
      * 
-     * @param defaultPort   start the server with this port if none is APP_PORT env variable is not set
+     * @param defaultPort   start the server with this port if neither PORT nor APP_PORT env variable is set
      * @param defer         Set to true to skip server startup
      */
     async startup (defaultPort: number = 3000, defer?: boolean) {
         const { bootWithDetectedPort } = await import('@arkstack/common')
+        // Prefer the platform-provided PORT (e.g. Railway, Heroku) over APP_PORT when available.
         await bootWithDetectedPort<TApp, TRoutes, THandler>(async (port) => {
             await this.boot(port, defer)
-        }, Number(process.env.APP_PORT ?? defaultPort), this as never, defer)
+        }, Number(process.env.PORT ?? process.env.APP_PORT ?? defaultPort), this as never, defer)
     }
 
     /**

packages/driver-express/src/index.ts

@@ -1,7 +1,7 @@
 import express, { type ErrorRequestHandler, type Express, type Handler } from 'express'
 
 import { ArkstackKitDriver, PromiseOrValue } from '@arkstack/contract'
-import { Logger } from '@arkstack/common'
+import { Logger, env } from '@arkstack/common'
 import { defaultErrorHandler } from './error-handler'
 import { Middleware, MiddlewareConfig } from './types'
 import { resolveMiddleware } from '@arkstack/http'
@@ -118,15 +118,22 @@ export class ExpressDriver extends ArkstackKitDriver<Express, Handler> {
 
     /**
      * Starts the Express server on the specified port.
-     * 
-     * @param app 
-     * @param port 
+     *
+     * The bind host can be overridden with the `APP_HOST` (or `HOST`) env
+     * variable. It defaults to `0.0.0.0` so the server is reachable on all
+     * network interfaces, which platforms like Railway require for their
+     * healthcheck proxy to reach the app.
+     *
+     * @param app
+     * @param port
      */
     start (app: Express, port: number): void {
-        app.listen(port, () => {
+        const host = env('APP_HOST', env('HOST', '0.0.0.0'))
+
+        app.listen(port, host, () => {
             Logger.log([
                 ['Server is running on', 'white'],
-                [`http://localhost:${port}`, 'cyan']
+                [`http://${host}:${port}`, 'cyan']
             ], ' ')
         })
     }

packages/driver-h3/src/index.ts

@@ -3,7 +3,7 @@ import { H3, H3Event, serve, toResponse } from 'h3'
 import { Middleware, MiddlewareConfig } from './types'
 
 import { Middleware as H3BaseMiddleware } from 'clear-router/types/h3'
-import { Logger } from '@arkstack/common'
+import { Logger, env } from '@arkstack/common'
 import { defaultErrorHandler } from './error-handler'
 import { resolveMiddleware } from '@arkstack/http'
 import { staticAssetHandler } from './middlewares'
@@ -126,15 +126,22 @@ export class H3Driver extends ArkstackKitDriver<H3, H3Middleware> {
 
     /**
      * Starts the H3 server on the specified port.
-     * 
-     * @param app 
-     * @param port 
+     *
+     * The bind host can be overridden with the `APP_HOST` (or `HOST`) env
+     * variable. It defaults to `0.0.0.0` so the server is reachable on all
+     * network interfaces, which platforms like Railway require for their
+     * healthcheck proxy to reach the app.
+     *
+     * @param app
+     * @param port
      */
     start (app: H3, port: number): void {
-        serve(app, { port, silent: true }).ready().then(() => {
+        const host = env('APP_HOST', env('HOST', '0.0.0.0'))
+
+        serve(app, { port, hostname: host, silent: true }).ready().then(() => {
             Logger.log([
                 ['Server is running on', 'white'],
-                [`http://localhost:${port}`, 'cyan']
+                [`http://${host}:${port}`, 'cyan']
             ], ' ')
         })
     }

templates/express/.env.example

@@ -1,6 +1,10 @@
 APP_NAME="Arkstack"
 APP_URL="http://localhost:3000"
 APP_PORT=3000
+# Host the server binds to. Defaults to 0.0.0.0 (all interfaces).
+# Set to localhost to restrict access to the local machine only.
+APP_HOST=0.0.0.0
+FILESYSTEM_DISK="local"
 
 TWO_FACTOR_ENCRYPTION_KEY="SRNysvjD139E6hrZfS8If7pQi0Uv/2ZBXb6fAT+agDZNpbfIAnVyHHvholN9c74v"
 JWT_SECRET="your-jwt-secret"
@@ -14,4 +18,11 @@ MAIL_SECURE=false
 MAIL_USERNAME="no-reply@example.com"
 MAIL_PASSWORD="password"
 MAIL_FROM_ADDRESS="no-reply@example.com"
-MAIL_TEST_ADDRESS=""
+MAIL_TEST_ADDRESS=
+
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_DEFAULT_REGION=
+AWS_BUCKET=
+AWS_URL=
+AWS_ENDPOINT=

templates/h3/.env.example

@@ -1,11 +1,16 @@
 APP_NAME="Arkstack"
 APP_URL="http://localhost:3000"
 APP_PORT=3000
+# Host the server binds to. Defaults to 0.0.0.0 (all interfaces).
+# Set to localhost to restrict access to the local machine only.
+APP_HOST=0.0.0.0
+FILESYSTEM_DISK="local"
 
 TWO_FACTOR_ENCRYPTION_KEY="SRNysvjD139E6hrZfS8If7pQi0Uv/2ZBXb6fAT+agDZNpbfIAnVyHHvholN9c74v"
 JWT_SECRET="your-jwt-secret"
 JWT_EXPIRES_IN="1h"
 
+
 DATABASE_URL="postgres://postgres:postgres@localhost:5432/arkstark_test?schema=public"
 
 MAIL_HOST="localhost"
@@ -14,4 +19,11 @@ MAIL_SECURE=false
 MAIL_USERNAME="no-reply@example.com"
 MAIL_PASSWORD="password"
 MAIL_FROM_ADDRESS="no-reply@example.com"
-MAIL_TEST_ADDRESS=""
+MAIL_TEST_ADDRESS=
+
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_DEFAULT_REGION=
+AWS_BUCKET=
+AWS_URL=
+AWS_ENDPOINT=