Production Deployment

Harpia is designed exclusively for the Bun runtime. This means your deployment environments must support executing Bun natively.

Because Harpia relies on recent advancements in Bun’s module resolution, testing tools, and native APIs, Bun v1.2.0 or higher is the minimum requirement.

Deployment Targets

1. Traditional Servers (VPS / Bare Metal)

Deploying to a standard Linux VPS (like DigitalOcean, Linode, or AWS EC2) is incredibly fast.

# Install Bun
curl -fsSL https://bun.sh/install | bash

# Clone your project
git clone https://github.com/your-org/your-project.git
cd your-project

# Install dependencies (blazingly fast)
bun install

# Apply database migrations to production
bun harpia deploy

# Start production server
ENV=production bun run start

2. Containerised Deployment (Docker)

For Kubernetes or Docker Swarm environments, use the official oven/bun image.

# Dockerfile
FROM oven/bun:1.2.0-alpine

# Set working directory
WORKDIR /app

# Copy dependencies and install
COPY package.json bun.lock /app/
RUN bun install --frozen-lockfile

# Copy the full source
COPY . .

# Apply pending migrations (no prompts, production-safe)
RUN bun harpia deploy

# Expose the application port
EXPOSE 3000

# Start the application
CMD ["bun", "run", "start"]

3. Platform-as-a-Service (PaaS)

Modern PaaS providers have excellent, out-of-the-box support for Bun.

Recommended Providers:

• Railway.app: Natively detects bun.lock and builds using the Bun environment automatically.
• Render.com: Select the Docker runtime and provide the Dockerfile above, or use their Native Environment and specify bun start.
• Fly.io: Works seamlessly via their Dockerfile generation.

For all PaaS deployments, ensure you:

1. Select the Bun buildpack or runtime.
2. Ensure your start script is defined in package.json ("start": "bun harpia start").
3. Populate the necessary Environment Variables (e.g., DB_URL, JWT_SECRET, ENV=production).

Configuration

Essential Environment Variables

Ensure your production environment possesses the correct variables. Harpia reads these at boot via app/config/.

ENV=production
PORT=3000
DB_URL="postgresql://user:pass@production-host:5432/mydb"
JWT_SECRET="your-secure-production-secret"

[!IMPORTANT] Harpia uses ENV (not NODE_ENV) and DB_URL (not DATABASE_URL). Using the wrong variable names will cause the application to boot with incorrect settings.

Performance Tuning

Harpia is naturally highly performant thanks to Bun, but you can optimise it further:

# Enable SMOL mode to reduce memory footprint (Useful for micro-instances <512MB RAM)
bun run --smol start/server.ts

[!WARNING] Do not use bun run dev (or the --hot flag) in production. Hot reloading consumes additional memory to watch file system changes and is exclusively meant for local development.

Monitoring

Harpia projects typically expose a health check endpoint to integrate with Docker Swarm, Kubernetes liveness probes, or NGINX upstreams.

// modules/health/controllers/check.ts
import type { Request, Response } from "@harpiats/core";

export const healthCheck = async (req: Request, res: Response) => {
  return res.status(200).json({
    status: "healthy",
    runtime: "Bun",
    version: Bun.version,
    timestamp: new Date().toISOString(),
  });
};