Best Practices

SolidQueue vs Sidekiq

If your only reason for declaring a redis: dep is to run Sidekiq, consider switching to SolidQueue instead. SolidQueue is database-backed and ships with Rails 8 — no Redis dep needed. Removing Redis saves consumers money (every declared dep adds infrastructure overhead).

If your app genuinely needs Redis for caching, pub/sub, or ActionCable, declare the redis: dep — but consider whether SolidCache or SolidCable could replace the need entirely.

Puma workers and memory

Each Puma worker consumes ~150–300 MB on a typical Rails app. Size your WEB_CONCURRENCY accordingly:

Declare WEB_CONCURRENCY in your env: list so consumers can tune it.

Asset precompilation

Run rails assets:precompile in your Dockerfile build stage, not at boot time. Precompiling at container start blocks traffic, consumes extra memory, and fails if the filesystem is read-only.

RUN SECRET_KEY_BASE=placeholder rails assets:precompile

Skip Rails encrypted credentials

Don't ship a master.key in your image. Use env: declarations instead — Kyper injects them as K8s Secrets. Your .kyperignore should exclude config/master.key and config/credentials.yml.enc.

Don't use PM2 inside Docker

PM2 is a process manager that fights with Kubernetes' own restart and lifecycle management. Run your app directly — CMD ["node", "dist/index.js"]. K8s handles restarts; your process just needs to exit cleanly on SIGTERM.

Cap the V8 heap on Hobby and Basic

V8's default memory limit is ~1.5 GB — more than the entire 512 MB allocation on Hobby and Basic. Set an explicit cap to avoid OOMKill:

CMD ["node", "--max-old-space-size=400", "dist/index.js"]

Leave ~100 MB headroom for the OS and Node overhead beyond the V8 heap.

TypeScript: build in Docker, don't ship source

Compile TypeScript in a build stage. Only copy the compiled dist/ output to your final image — no ts-node, no source files, no devDependencies at runtime.

Graceful shutdown

Many Node.js frameworks don't wire SIGTERM by default. Add it explicitly:

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

WSGI vs ASGI

Use Gunicorn for Flask and Django (WSGI). Use uvicorn + Gunicorn for FastAPI or Django Channels (ASGI):

# Flask / Django (WSGI)
CMD ["gunicorn", "myapp.wsgi:application", "--bind", "0.0.0.0:3000", "--workers", "2"]

# FastAPI (ASGI)
CMD ["gunicorn", "main:app", "-k", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:3000", "--workers", "2"]

Worker count

Gunicorn's default formula (2 × CPU + 1) can OOMKill on small tiers. Use --workers 1 on Hobby and Basic, --workers 2 on Pro, and --workers 4 on Turbo. Declare a GUNICORN_WORKERS env var so consumers can tune it.

Static files (Django)

Use WhiteNoise to serve Django static files from the app process itself — no separate nginx or static file server needed. Add it to your middleware and run collectstatic in your Dockerfile.

No virtualenv inside Docker

Don't create a venv inside your image. Install packages directly into the system Python (or use a build stage). The container itself is the isolation layer.

Multi-stage builds for minimal images

Go compiles to a static binary. Use a multi-stage build with a minimal final image — Go apps have the smallest footprint of any common stack on Kyper:

FROM golang:1.23-alpine AS build
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /app/server ./cmd/server

FROM alpine:3.20
COPY --from=build /app/server /server
CMD ["/server"]

CGO and scratch images

If your app uses CGO (SQLite, certain crypto libs), FROM scratch won't work — you need libc. Use FROM alpine or FROM gcr.io/distroless/base instead.

Graceful shutdown

ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM)
defer stop()

// pass ctx to your server and shut down cleanly when it's canceled