Operations + Deployment

Deploy NioFlow apps with predictable startup behavior, observable health, and safe runtime defaults. This page covers both release mechanics and day-2 operations basics.

Deployment Strategy

Treat deployment as a repeatable process, not a manual push. Build immutable artifacts, configure env values per environment, verify readiness endpoints, and only then shift traffic.

release-flow

11) Build once (CI) and publish artifact
22) Promote same artifact to staging/prod
33) Inject environment-specific variables at runtime
44) Validate /_ready before accepting traffic
55) Roll forward or roll back based on health + logs

Production Build with CLI

You can use the CLI to package your application for deployment. This generates the fat JAR in your target directory.

If you scaffolded with nioflow new, the Maven Wrapper is already included. Run nioflow dev locally and use ./mvnw package in CI.

cli-build

1# From project root
2./mvnw clean package -DskipTests
3
4# Runnable artifact will be in:
5# target/my-app-1.0-SNAPSHOT-jar-with-dependencies.jar

Required Environment Variables

Keep environment values outside source control. Use your platform secret manager for all sensitive values.

required-env

1PORT=8080
2JWT_SECRET=replace-with-32-plus-char-secret
3NIOFLOW_CORS_ORIGIN=https://your-frontend-domain
4NIOFLOW_ENABLE_DB=false
5NIOFLOW_CHAOS_ENABLED=false
6NIOFLOW_REPLAY_ENABLED=false

Recommended Production Runtime Values

Warning: NIOFLOW_EXPOSE_ERROR_DETAILS=true will leak full Java exception stack traces directly to HTTP clients. This should remain false in production to prevent exposing internal application structure.

prod-runtime-env

1NIOFLOW_EXPOSE_ERROR_DETAILS=false
2NIOFLOW_DISABLE_AUTH=false
3NIOFLOW_CHAOS_ENABLED=false
4NIOFLOW_REPLAY_ENABLED=false
5JAVA_TOOL_OPTIONS=-Xms256m -Xmx512m -XX:+UseG1GC

Docker Deployment

Container deployments are ideal for consistency. Ensure the image runs as non-root and only exposes the required port.

docker-build-run

1docker build -t nioflow-app .
2docker run --rm -p 8080:8080   -e PORT=8080   -e JWT_SECRET=replace-with-32-plus-char-secret   -e NIOFLOW_ENABLE_DB=false   nioflow-app

Render / Railway Quick Setup

These platforms provide port and process orchestration. Keep startup command simple and rely on environment variables for all deployment-specific behavior.

cloud-vars

1PORT = (auto provided by platform)
2JWT_SECRET = your long random secret
3NIOFLOW_CORS_ORIGIN = https://your-frontend-domain
4NIOFLOW_ENABLE_DB = false

Health + Readiness Checks

Health indicates the process is alive, readiness indicates the service can accept production traffic.

probe-endpoints

1curl -i http://localhost:8080/_health
2curl -i http://localhost:8080/_ready
3curl -i http://localhost:8080/metrics

Operations Incident Basics

incident-checklist

11) Confirm failing endpoint and scope
22) Check /_health and /_ready status
33) Review application logs around the failure window
44) Verify env values and secrets are present
55) Roll back to last healthy release if needed
66) Capture root cause and preventive action in runbook

Post-Deploy Verification

post-deploy-smoke

1curl -fsS https://your-api/_health
2curl -fsS https://your-api/_ready
3curl -fsS https://your-api/api/tasks/
4
5# Expected: all commands return successful HTTP responses

Production Checklist

go-live

1[x] Global onError handler registered
2[x] Graceful shutdown hook registered
3[x] Protected routes gated by AuthMiddleware
4[x] JWT secret validated at startup
5[x] Integration tests assert auth enforcement and observability
6[x] Integration tests assert 404 vs 405 distinction
7[x] Integration tests assert middleware ordering and header preservation
8[x] Integration tests assert circuit breaker state transitions
9[x] TLS plan finalized (listenSecure or reverse proxy termination)
10[x] Runtime sizing validated with load testing (k6)
11[x] Vulnerability scanning enforced in CI (OWASP) — 271 tests passing, 83% instruction coverage

PreviousAdvanced Features NextAPI Reference