Agent skill
bun-deploy
Generate optimized Docker images for Bun applications. Use when deploying to containers, minimizing image sizes, setting up CI/CD pipelines, or deploying to Kubernetes.
Install this agent skill to your Project
npx add-skill https://github.com/DaleSeo/bun-skills/tree/main/skills/bun-deploy
Metadata
Additional technical details for this skill
- tags
- author
- dale
- category
- bun-runtime
SKILL.md
Bun Docker Deployment
Create optimized Docker images for Bun applications. Bun's small runtime and binary compilation reduce image sizes by 88MB+ compared to Node.js.
Quick Reference
For detailed patterns, see:
- Dockerfile Templates: dockerfile-templates.md - 12+ optimized templates
- Kubernetes: kubernetes.md - K8s manifests, HPA, ingress
- CI/CD: ci-cd.md - GitHub Actions, GitLab CI, build scripts
- Multi-Platform: multi-platform.md - ARM64/AMD64 builds
Core Workflow
1. Check Prerequisites
# Verify Docker is installed
docker --version
# Verify Bun is installed locally
bun --version
# Check if project is ready for deployment
ls -la package.json bun.lockb
2. Determine Deployment Strategy
Ask the user about their needs:
- Application Type: Web server, API, worker, or CLI
- Image Size Priority: Minimal size (40MB binary) vs. debugging tools (90MB Alpine)
- Platform: Single platform or multi-platform (AMD64 + ARM64)
- Orchestration: Docker Compose, Kubernetes, or standalone containers
3. Create Production Dockerfile
Choose the appropriate template based on needs:
Standard Multi-Stage (Recommended)
# syntax=docker/dockerfile:1
FROM oven/bun:1-alpine AS deps
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production
FROM oven/bun:1-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN bun run build
FROM oven/bun:1-alpine AS runtime
WORKDIR /app
RUN addgroup --system --gid 1001 bunuser && \
adduser --system --uid 1001 bunuser
COPY --from=deps --chown=bunuser:bunuser /app/node_modules ./node_modules
COPY --from=builder --chown=bunuser:bunuser /app/dist ./dist
COPY --from=builder --chown=bunuser:bunuser /app/package.json ./
USER bunuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
CMD bun run healthcheck.ts || exit 1
CMD ["bun", "run", "dist/index.js"]
Minimal Binary (40MB)
For smallest possible images:
FROM oven/bun:1-alpine AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun build ./src/index.ts --compile --outfile server
FROM gcr.io/distroless/base-debian12
COPY --from=builder /app/server /server
EXPOSE 3000
ENTRYPOINT ["/server"]
For other scenarios (monorepo, database apps, CLI tools, etc.), see dockerfile-templates.md.
4. Create .dockerignore
node_modules
bun.lockb
dist
*.log
.git
.env
.env.local
tests/
*.test.ts
coverage/
.vscode/
.DS_Store
Dockerfile
docker-compose.yml
5. Create Health Check Script
Create healthcheck.ts:
#!/usr/bin/env bun
const port = process.env.PORT || 3000;
const healthEndpoint = process.env.HEALTH_ENDPOINT || '/health';
try {
const response = await fetch(`http://localhost:${port}${healthEndpoint}`, {
method: 'GET',
timeout: 2000,
});
if (response.ok) {
process.exit(0);
} else {
console.error(`Health check failed: ${response.status}`);
process.exit(1);
}
} catch (error) {
console.error('Health check error:', error);
process.exit(1);
}
Add health endpoint to your server:
app.get('/health', (req, res) => {
res.json({
status: 'ok',
timestamp: Date.now(),
uptime: process.uptime(),
});
});
6. Build and Test Image
# Build image
docker build -t myapp:latest .
# Check image size
docker images myapp:latest
# Run container
docker run -p 3000:3000 myapp:latest
# Test health endpoint
curl http://localhost:3000/health
7. Setup for Environment
For Local Development with Docker Compose:
Create docker-compose.yml:
version: '3.8'
services:
app:
build:
context: .
dockerfile: Dockerfile.dev
ports:
- "3000:3000"
volumes:
- .:/app
- /app/node_modules
environment:
- NODE_ENV=development
depends_on:
- db
- redis
db:
image: postgres:16-alpine
environment:
POSTGRES_USER: user
POSTGRES_PASSWORD: pass
POSTGRES_DB: mydb
ports:
- "5432:5432"
redis:
image: redis:7-alpine
ports:
- "6379:6379"
Run with: docker-compose up
For Kubernetes Deployment:
See kubernetes.md for complete manifests including:
- Deployment configuration
- Service and Ingress
- Secrets and ConfigMaps
- Horizontal Pod Autoscaling
- Resource limits optimized for Bun
For CI/CD:
See ci-cd.md for:
- GitHub Actions workflow
- GitLab CI configuration
- Build and push scripts
- Automated deployments
For Multi-Platform (ARM64 + AMD64):
See multi-platform.md for:
- Multi-platform Dockerfile
- Buildx configuration
- Testing on different architectures
8. Update package.json
Add Docker scripts:
{
"scripts": {
"docker:build": "docker build -t myapp:latest .",
"docker:run": "docker run -p 3000:3000 myapp:latest",
"docker:dev": "docker-compose up",
"docker:clean": "docker system prune -af"
}
}
Image Size Comparison
Bun produces significantly smaller images:
| Configuration | Size | Use Case |
|---|---|---|
| Bun Binary (distroless) | ~40 MB | Production (minimal) |
| Bun Alpine | ~90 MB | Production (standard) |
| Node.js Alpine | ~180 MB | Baseline comparison |
88MB+ savings with Bun!
Security Best Practices
- Use non-root user (included in Dockerfiles above)
- Scan for vulnerabilities:
docker scan myapp:latest - Use official base images:
oven/bunis official - Keep images updated: Rebuild regularly with latest Bun
- Never hardcode secrets: Use environment variables or secret managers
Optimization Tips
Layer caching:
# Copy dependencies first (changes less often)
COPY package.json bun.lockb ./
RUN bun install
# Copy source code last (changes more often)
COPY . .
RUN bun run build
Reduce layer count:
# Combine RUN commands
RUN bun install && \
bun run build && \
rm -rf tests/
Minimize final image:
# Only copy what's needed in runtime
COPY --from=builder /app/dist ./dist
# Don't copy: src/, tests/, .git/, node_modules (if using binary)
Completion Checklist
- ✅ Dockerfile created (multi-stage or binary)
- ✅ .dockerignore configured
- ✅ Health check implemented
- ✅ Non-root user configured
- ✅ Image built and tested locally
- ✅ Image size verified (<100MB for Alpine, <50MB for binary)
- ✅ Environment configuration ready (docker-compose or K8s)
- ✅ CI/CD pipeline configured (if needed)
Next Steps
After basic deployment:
- Monitoring: Add Prometheus metrics endpoint
- Logging: Configure structured logging
- Secrets: Set up proper secret management
- Scaling: Configure horizontal pod autoscaling (K8s)
- CI/CD: Automate builds and deployments
- Multi-region: Deploy to multiple regions for redundancy
For detailed implementations, see the reference files linked above.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
deno-to-bun
Migrate Deno projects to Bun with API compatibility analysis. Use when converting Deno.* APIs to Bun equivalents, migrating from Deno Deploy, or updating permissions model and import maps.
bun-build
Create optimized production bundles with Bun's native bundler. Use when building applications for production, optimizing bundle sizes, setting up multi-environment builds, or replacing webpack/esbuild/rollup.
bun-test
Configure Bun's built-in test runner with Jest-compatible APIs. Use when setting up testing infrastructure, writing unit/integration/snapshot tests, migrating from Jest, or configuring test coverage. 3-10x faster than Jest.
bun-init
Initialize a new Bun project with TypeScript and optimal configuration. Use when starting a new Bun project or converting a directory to a Bun project.
cloudflare-to-bun
Migrate Cloudflare Workers to Bun with runtime compatibility analysis. Use when converting Workers to Bun, migrating from Cloudflare bindings, or moving from edge to server deployment.
bun-dev-server
Set up high-performance development servers with Hot Module Replacement. Use when creating dev servers for web apps, setting up React Fast Refresh, or configuring API servers with live reload.
Didn't find tool you were looking for?