Bun Dockerfile

# ============================================================================
# Created by https://Dockerfile.io/
# LANGUAGE-SPECIFIC TEMPLATE for Bun
# Website: https://bun.sh/
# Repository: https://github.com/oven-sh/bun
# ============================================================================

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# TEMPLATE OVERVIEW & USAGE NOTES
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# • TEMPLATE TYPE: LANGUAGE-SPECIFIC TEMPLATE
# • PURPOSE: Bun runtime environment for fast JavaScript/TypeScript applications
# • DESIGN PHILOSOPHY: All-in-one toolkit (runtime, bundler, test runner, package manager)
# • COMBINATION GUIDANCE: Combine with framework templates or use standalone
# • SECURITY CONSIDERATIONS: Non-root execution, minimal base image
# • BEST PRACTICES: Fast package management, built-in tooling, performance optimization
# • OFFICIAL SOURCES: Bun documentation and performance guidelines

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# BASE IMAGE - Bun runtime
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FROM oven/bun:1.0-alpine

# Build arguments for environment configuration
ARG BUN_VERSION=1.0
ARG BUILD_ID=unknown
ARG COMMIT_SHA=unknown
ARG NODE_ENV=production

# Environment variables for runtime
ENV BUN_VERSION=${BUN_VERSION} \
    BUILD_ID=${BUILD_ID} \
    COMMIT_SHA=${COMMIT_SHA} \
    NODE_ENV=${NODE_ENV} \
    BUN_INSTALL=/usr/local \
    PATH=/usr/local/bin:${PATH}

# Security configuration
ARG APP_USER=appuser
ARG APP_GROUP=appgroup
ARG APP_UID=1001
ARG APP_GID=1001

# Create non-root user and group
RUN addgroup -g ${APP_GID} -S ${APP_GROUP} && \
    adduser -S -u ${APP_UID} -G ${APP_GROUP} ${APP_USER}

# Set working directory
WORKDIR /app

# Copy dependency files first for optimal layer caching
COPY package.json bun.lockb ./

# Install production dependencies
RUN bun install --production --frozen-lockfile && \
    bun pm cache rm && \
    rm -rf /tmp/*

# Copy application source code
COPY --chown=${APP_USER}:${APP_GROUP} . .

# Set permissions
RUN chown -R ${APP_USER}:${APP_GROUP} /app && \
    chmod -R 750 /app

# Switch to non-root user
USER ${APP_USER}

# Expose application port (adjust based on your application)
EXPOSE 3000

# Health check for container orchestration
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD bun run health-check.js || exit 1

# Default command (override in child images or runtime)
CMD ["bun", "run", "src/index.js"]

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# USAGE EXAMPLES & BEST PRACTICES
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# USAGE EXAMPLES
# ==============

# Example 1: Build production image
# docker build -t my-bun-app:prod .

# Example 2: Build with custom build arguments
# docker build \
#   --build-arg BUILD_ID=v1.0.0 \
#   --build-arg COMMIT_SHA=$(git rev-parse HEAD) \
#   -t my-bun-app:prod .

# Example 3: Run development with hot reload
# docker run -d -p 3000:3000 -v $(pwd):/app --name bun-dev my-bun-app:dev

# Example 4: Run production with resource limits
# docker run -d \
#   -p 3000:3000 \
#   --restart unless-stopped \
#   --memory 128m \
#   --cpus 0.5 \
#   --name bun-app \
#   my-bun-app:prod

# Example 5: Run with Docker Compose
# docker-compose up -d

# Example 6: Build for multiple architectures
# docker buildx build --platform linux/amd64,linux/arm64 -t my-bun-app:multi-arch .

# Example 7: Run with health check verification
# docker run -d -p 3000:3000 --health-cmd="bun run health-check.js || exit 1" --name bun-app my-bun-app:prod

# Example 8: Run with environment variables
# docker run -d -p 3000:3000 -e NODE_ENV=production -e DATABASE_URL=postgres://user:pass@db:5432/app --name bun-app my-bun-app:prod

# BEST PRACTICES
# ==============

# Security Best Practices:
# • Always use non-root user for runtime execution
# • Use specific base image versions (avoid 'latest' tags)
# • Set appropriate file permissions for application directories
# • Regularly update Bun and Alpine dependencies
# • Scan images for vulnerabilities using tools like Trivy or Grype

# Performance Optimization:
# • Use multi-stage builds to minimize final image size
# • Leverage layer caching by copying package.json and bun.lockb first
# • Use Alpine base images for smaller footprint
# • Set appropriate resource limits (memory, CPU) in production
# • Use Bun's built-in optimizations for faster builds

# Development Workflow:
# • Use separate development and production Dockerfiles or targets
# • Mount source code as volume for hot reload during development
# • Set up proper .dockerignore to exclude node_modules, .git, build artifacts
# • Use Docker Compose for local development with databases
# • Implement health checks for container orchestration

# Production Deployment:
# • Use specific version tags for production images
# • Implement proper logging with structured JSON format
# • Set up automated builds and security scanning
# • Use container orchestration (Kubernetes, Docker Swarm) for scaling
# • Implement zero-downtime deployment strategies

# Bun-Specific Considerations:
# • Use bun.lockb for deterministic dependency installation
# • Leverage Bun's built-in TypeScript support without compilation step
# • Use Bun's test runner for faster test execution
# • Take advantage of Bun's WebSocket and SQLite support
# • Use Bun's bundler for optimized production builds