Web Services

What is a Web Service?

A web service is any process that listens on a TCP port and serves HTTP(S) traffic. StackBlaze provisions a Kubernetes Deployment and Service, a TLS-terminated Ingress, and a public URL in the form https://your-service.stackblaze.app. You can also attach a custom domain.

Web services support HTTP/1.1, HTTP/2, and WebSockets. There is no need to terminate TLS yourself, the Ingress controller handles it and forwards plain HTTP to your container.

Port detection

StackBlaze reads the PORT environment variable to know which port your container listens on. The default is 8080. Always bind to 0.0.0.0 (not 127.0.0.1) so the pod can receive traffic from other pods in the cluster.

// Node.js example
const port = process.env.PORT || 8080
app.listen(port, '0.0.0.0', () => {
  console.log(`Listening on port ${port}`)
})

# Python / Gunicorn example
# StackBlaze sets PORT automatically
# gunicorn reads $PORT via --bind flag
# Procfile: web: gunicorn app:app --bind 0.0.0.0:$PORT

Health checks

StackBlaze uses Kubernetes readiness probes to determine when a new pod is ready to receive traffic. Traffic is only sent to a pod after it passes the readiness check. If a pod fails health checks repeatedly, it is restarted automatically (liveness probe).

Default health check

By default, StackBlaze sends HTTP GET requests to / on your service port. A 2xx or 3xx response is considered healthy.

Custom health check path

Specify a custom health check path in Service Settings → Health Check. A dedicated endpoint like /health or /ping is recommended, it should return quickly without triggering expensive database queries.

// Recommended: lightweight health endpoint
app.get('/health', (req, res) => {
  res.json({ status: 'ok', uptime: process.uptime() })
})

Health check settings

Start command

The start command is the entrypoint of your container, it is what StackBlaze runs to start your application. It should start your HTTP server and block (not exit). If it exits, Kubernetes considers the pod failed and restarts it.

Scaling

You can scale web services horizontally (more replicas) or vertically (more CPU and memory per replica). StackBlaze supports both manual and automatic scaling.

Manual scaling

From the dashboard, go to Service → Settings → Scaling. Set the number of replicas. The change takes effect immediately, no redeploy needed.

# Scale to 3 replicas via CLI
stackblaze scale api --replicas 3

Autoscaling

Set a minimum and maximum replica count and StackBlaze's autoscaler will adjust replicas based on CPU utilization (target: 70%). Scale-out happens within seconds; scale-in is delayed 5 minutes to avoid oscillation.

Zero-downtime rolling updates

Every deploy uses a Kubernetes rolling update strategy. New pods are started and must pass health checks before old pods are terminated. The rolling update parameters:

This means a deploy with 2 replicas will temporarily run 3 pods: the 2 old ones serving traffic and 1 new one warming up. Once the new pod is healthy, one old pod is terminated, and so on until all replicas are updated.

Node.js example

import express from 'express'

const app = express()
const port = parseInt(process.env.PORT || '8080', 10)

app.use(express.json())

app.get('/health', (req, res) => {
  res.json({ status: 'ok' })
})

app.get('/', (req, res) => {
  res.json({ message: 'Hello from StackBlaze!' })
})

app.listen(port, '0.0.0.0', () => {
  console.log(`Server listening on port ${port}`)
})

Python example

from fastapi import FastAPI
import os

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

@app.get("/")
def root():
    return {"message": "Hello from StackBlaze!"}

# Start with: uvicorn main:app --host 0.0.0.0 --port $PORT

Environment variables

StackBlaze injects the following variables automatically into every web service:

Read more about environment variables in Security → Environment Variables.