Dart Cloud Native Buildpack

A standard Cloud Native Buildpack (CNB) for compiling and containerizing Dart (>= 3.9) server and command-line applications into minimal, secure, and production-ready OCI container images without writing a Dockerfile.

---

Features

• Modern Dart Build Engine: Uses dart build cli to produce self-contained, AOT-compiled native executables with native assets and build hooks (hook/build.dart) support.
• Automated SDK Provisioning: Dynamically fetches and installs the official Dart SDK across stable, beta, dev, and main channels for both x64 and arm64 Linux platforms.
• Layer Caching:
  • SDK Layer (dart-sdk): Caches SDK downloads across builds. The SDK is marked launch = false, ensuring zero Dart SDK runtime bloat in the final exported image.
  • Dependency Cache (pub-cache): Dedicated PUB_CACHE layer that persists downloaded package tarballs and git dependencies across builds.
• Deterministic Dependency Resolution: Runs dart pub get with --no-precompile for faster builds, and automatically applies --enforce-lockfile when pubspec.lock is present.
• Intelligent Entrypoint Discovery:
  1. BP_DART_ENTRYPOINT environment variable (explicit override)
  2. executables: section in pubspec.yaml
  3. Conventional file paths: bin/server.dart → bin/main.dart → single .dart file in bin/
• Dynamic Asset & Library Linking: Automatically configures LD_LIBRARY_PATH to link compiled C/C++ dynamic libraries from bundle/lib/.
• Configurable Launch Processes: Generates standard launch.toml with default web and app processes respecting the standard $PORT environment variable.

---

Requirements

• Dart SDK Version: Dart >= 3.9
• Container Tooling: pack CLI with Podman or Docker.

---

Quick Start

1. Build an Image from Source

You can build a container image using the pack CLI by pointing directly to this buildpack repository:

pack build my-dart-app \
  --path ./samples/shelf_server \
  --buildpack /path/to/dart_buildpack \
  --builder paketobuildpacks/builder-jammy-base

Note for Podman users: Set --docker-host=inherit or configure the Podman socket:

pack build my-dart-app \
  --path ./samples/shelf_server \
  --buildpack /path/to/dart_buildpack \
  --builder paketobuildpacks/builder-jammy-base \
  --docker-host=inherit

2. Run the Container

# Using Podman
podman run -p 8080:8080 -e PORT=8080 my-dart-app

# Or using Docker
docker run -p 8080:8080 -e PORT=8080 my-dart-app

Verify your application:

curl http://localhost:8080/

---

Configuration Options

Configure build behavior by passing environment variables at build time (e.g., via pack build --env <KEY>=<VALUE> or platform environment directories):

Environment Variable	Description	Default	Supported Values
BP_DART_VERSION	Target Dart SDK version to download	latest	Semver string (e.g. 3.9.0, 3.10.1) or latest
BP_DART_CHANNEL	Release channel for Dart SDK download	stable	stable, beta, dev, main
BP_DART_ENTRYPOINT	Explicit path to the application entrypoint file	(auto)	Relative path (e.g. bin/api.dart)
BP_DART_OFFLINE	Force offline dependency resolution from cache	false	true, false, 1, 0
BP_DART_PUB_HOSTED_URL	URL of private package repository	(none)	URL (e.g. https://pub.myorg.com/)
BP_DART_PUB_TOKEN_ENV	Environment variable name holding private repository token	(none)	Env var name (e.g. MYORG_PUB_TOKEN)
BP_DART_PUB_TOKEN	Direct authentication secret for private repository	(none)	Secret token string

Private Package Registries

If your app depends on packages hosted in a private repository (e.g. GitLab Package Registry, self-hosted unpub, or Cloudsmith), pass the repository URL and token environment variable at build time:

pack build my-dart-app \
  --env BP_DART_PUB_HOSTED_URL="https://pub.myorg.com" \
  --env BP_DART_PUB_TOKEN_ENV="MY_PUB_TOKEN" \
  --env MY_PUB_TOKEN="$MY_PUB_TOKEN" \
  --builder paketobuildpacks/builder-jammy-base

---

Repository Structure

├── bin/
│   ├── detect          # CNB detection script (inspects pubspec.yaml)
│   └── build           # CNB build script (SDK, pub cache, compilation, launch.toml)
├── buildpack.toml      # Buildpack descriptor (API 0.10, Linux x64/arm64 targets)
├── samples/
│   └── shelf_server/   # Sample Dart HTTP web server using Shelf & Shelf Router
├── test/
│   ├── detect_test.sh        # Unit tests for bin/detect
│   ├── sdk_layer_test.sh     # Unit tests for SDK provisioning and caching
│   ├── pub_layer_test.sh     # Unit tests for pub caching and dependency resolution
│   ├── build_compile_test.sh # Unit tests for dart build cli compilation and launch.toml
│   └── integration_test.sh   # End-to-end integration test with live server verification

---

Running Tests

Execute the automated test suites locally:

# Run all unit test suites
./test/detect_test.sh
./test/sdk_layer_test.sh
./test/pub_layer_test.sh
./test/build_compile_test.sh

# Run end-to-end integration test
./test/integration_test.sh

---

License

MIT License