Web Services

What is a Web Service?

A web app is any process that listens on a TCP port and serves HTTP(S) traffic. StackBlaze gives it a public URL in the form https://your-app.stackblaze.app. You can also attach a custom domain.

Web apps support HTTP/1.1, HTTP/2, and WebSockets. You do not terminate TLS yourself — the platform handles it and forwards 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 the load balancer.

// 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 health checks to decide when a new replica is ready to receive traffic. Traffic is only sent after the readiness check passes. If an instance fails health checks repeatedly, it is restarted automatically.

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 should start your HTTP server and block (not exit). If it exits, the platform restarts the instance.

Scaling

You can scale web apps 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 the app → Settings → Scaling. Set the number of replicas. The change takes effect immediately, no rebuild needed. There is no npm CLI — use the dashboard or the REST API.

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 rolling update. New replicas start and must pass health checks before old replicas are stopped. The parameters:

This means a deploy with 2 replicas will temporarily run 3 instances: the 2 old ones serving traffic and 1 new one warming up. Once the new instance is healthy, one old instance is stopped, 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 PORT so the app knows which port to bind. Add your own variables in the dashboard. Do not rely on undocumented STACKBLAZE_* names.

Read more about environment variables in Security → Environment Variables.