From 05de92148bb46435a7d74c0ec1fd996c8351974c Mon Sep 17 00:00:00 2001 From: Snider Date: Thu, 29 Jan 2026 00:45:17 +0000 Subject: [PATCH] docs(examples): add build-* configuration examples Build configuration examples for testing and documentation: - build-minimal.yaml - Auto-detect everything - build-go-cli.yaml - Cross-platform CLI - build-go-wails.yaml - Desktop app with frontend - build-go-library.yaml - Library (no binary) - build-docker.yaml - Multi-arch container - build-docker-go.yaml - Go binary + Docker - build-linuxkit.yaml - Immutable Linux images - build-php-laravel.yaml - FrankenPHP + Laravel - build-multi-binary.yaml - Multiple binaries - build-full.yaml - All available options Co-Authored-By: Claude Opus 4.5 --- docs/examples/build-docker-go.yaml | 42 +++++++++ docs/examples/build-docker.yaml | 40 +++++++++ docs/examples/build-full.yaml | 121 ++++++++++++++++++++++++++ docs/examples/build-go-cli.yaml | 39 +++++++++ docs/examples/build-go-library.yaml | 23 +++++ docs/examples/build-go-wails.yaml | 46 ++++++++++ docs/examples/build-linuxkit.yaml | 33 +++++++ docs/examples/build-minimal.yaml | 7 ++ docs/examples/build-multi-binary.yaml | 51 +++++++++++ docs/examples/build-php-laravel.yaml | 50 +++++++++++ 10 files changed, 452 insertions(+) create mode 100644 docs/examples/build-docker-go.yaml create mode 100644 docs/examples/build-docker.yaml create mode 100644 docs/examples/build-full.yaml create mode 100644 docs/examples/build-go-cli.yaml create mode 100644 docs/examples/build-go-library.yaml create mode 100644 docs/examples/build-go-wails.yaml create mode 100644 docs/examples/build-linuxkit.yaml create mode 100644 docs/examples/build-minimal.yaml create mode 100644 docs/examples/build-multi-binary.yaml create mode 100644 docs/examples/build-php-laravel.yaml diff --git a/docs/examples/build-docker-go.yaml b/docs/examples/build-docker-go.yaml new file mode 100644 index 00000000..4542d7a9 --- /dev/null +++ b/docs/examples/build-docker-go.yaml @@ -0,0 +1,42 @@ +# Example: Go + Docker Build Configuration +# Build Go binary then containerize + +version: 1 + +project: + name: myservice + binary: myservice + +# First: build Go binary +build: + main: ./cmd/myservice + env: + CGO_ENABLED: "0" + GOOS: linux + ldflags: + - -s -w + - -X main.version={{.Version}} + +targets: + - os: linux + arch: amd64 + - os: linux + arch: arm64 + +# Then: build Docker image with the binary +docker: + dockerfile: Dockerfile + registry: ghcr.io + image: myorg/myservice + platforms: + - linux/amd64 + - linux/arm64 + tags: + - latest + - "{{.Version}}" + +# Dockerfile should COPY the built binary: +# +# FROM alpine:latest +# COPY myservice /usr/local/bin/myservice +# ENTRYPOINT ["/usr/local/bin/myservice"] diff --git a/docs/examples/build-docker.yaml b/docs/examples/build-docker.yaml new file mode 100644 index 00000000..3cd641da --- /dev/null +++ b/docs/examples/build-docker.yaml @@ -0,0 +1,40 @@ +# Example: Docker Build Configuration +# Multi-arch container image + +version: 1 + +project: + name: myservice + type: docker + +docker: + dockerfile: Dockerfile + context: . + registry: ghcr.io + image: myorg/myservice + + platforms: + - linux/amd64 + - linux/arm64 + + tags: + - latest + - "{{.Version}}" + - "{{.Version}}-alpine" + + build_args: + APP_VERSION: "{{.Version}}" + BUILD_DATE: "{{.Date}}" + + labels: + org.opencontainers.image.source: https://github.com/myorg/myservice + org.opencontainers.image.description: My Service + org.opencontainers.image.licenses: MIT + + # Optional: build stage target + target: production + + # Optional: cache settings + cache: + from: type=gha + to: type=gha,mode=max diff --git a/docs/examples/build-full.yaml b/docs/examples/build-full.yaml new file mode 100644 index 00000000..bd4f35c8 --- /dev/null +++ b/docs/examples/build-full.yaml @@ -0,0 +1,121 @@ +# Example: Full Build Configuration +# All available options + +version: 1 + +project: + name: myapp + binary: myapp + type: auto # auto, go, wails, docker, linuxkit, php + +build: + # Go build settings + main: ./cmd/myapp + + # Environment variables + env: + CGO_ENABLED: "0" + GOFLAGS: "-mod=readonly" + + # Build flags + flags: + - -trimpath + - -v + + # Linker flags + ldflags: + - -s -w + - -X main.version={{.Version}} + - -X main.commit={{.Commit}} + - -X main.date={{.Date}} + - -X main.builtBy=core + + # Build tags + tags: + - production + - netgo + +# Build targets +targets: + - os: linux + arch: amd64 + - os: linux + arch: arm64 + - os: linux + arch: "386" + - os: darwin + arch: amd64 + - os: darwin + arch: arm64 + - os: windows + arch: amd64 + - os: windows + arch: arm64 + - os: freebsd + arch: amd64 + +# Wails configuration (if type: wails) +wails: + frontend: ./frontend + install_cmd: install + build_cmd: build + dev_cmd: dev + +# Docker configuration (if type: docker or docker output enabled) +docker: + dockerfile: Dockerfile + context: . + registry: ghcr.io + image: myorg/myapp + platforms: + - linux/amd64 + - linux/arm64 + tags: + - latest + - "{{.Version}}" + build_args: + VERSION: "{{.Version}}" + labels: + org.opencontainers.image.source: https://github.com/myorg/myapp + target: production + cache: + from: type=gha + to: type=gha,mode=max + +# LinuxKit configuration (if type: linuxkit) +linuxkit: + config: .core/linuxkit/server.yml + formats: + - iso + - qcow2 + - docker + platforms: + - linux/amd64 + - linux/arm64 + +# Archive settings +archive: + format: tar.gz + format_windows: zip + name: "{{.Project}}-{{.Version}}-{{.OS}}-{{.Arch}}" + files: + - LICENSE + - README.md + - CHANGELOG.md + strip_parent: true + +# Checksum settings +checksum: + algorithm: sha256 + file: checksums.txt + +# Hooks +hooks: + pre_build: + - go generate ./... + - go mod tidy + post_build: + - echo "Build complete" + +# Output directory +output: dist diff --git a/docs/examples/build-go-cli.yaml b/docs/examples/build-go-cli.yaml new file mode 100644 index 00000000..22b21cab --- /dev/null +++ b/docs/examples/build-go-cli.yaml @@ -0,0 +1,39 @@ +# Example: Go CLI Build Configuration +# Cross-platform CLI tool + +version: 1 + +project: + name: mycli + binary: mycli + +build: + main: ./cmd/mycli + env: + CGO_ENABLED: "0" + flags: + - -trimpath + ldflags: + - -s -w + - -X main.version={{.Version}} + - -X main.commit={{.Commit}} + - -X main.date={{.Date}} + +targets: + - os: linux + arch: amd64 + - os: linux + arch: arm64 + - os: darwin + arch: amd64 + - os: darwin + arch: arm64 + - os: windows + arch: amd64 + +archive: + format: tar.gz + format_windows: zip + files: + - LICENSE + - README.md diff --git a/docs/examples/build-go-library.yaml b/docs/examples/build-go-library.yaml new file mode 100644 index 00000000..63fe5fb5 --- /dev/null +++ b/docs/examples/build-go-library.yaml @@ -0,0 +1,23 @@ +# Example: Go Library Build Configuration +# No binary output, just validation and testing + +version: 1 + +project: + name: mylib + type: library # No binary build + +build: + # Library-specific settings + env: + CGO_ENABLED: "0" + +# Test configuration +test: + race: true + cover: true + packages: + - ./... + +# No targets needed for library +# targets: [] diff --git a/docs/examples/build-go-wails.yaml b/docs/examples/build-go-wails.yaml new file mode 100644 index 00000000..8a952bca --- /dev/null +++ b/docs/examples/build-go-wails.yaml @@ -0,0 +1,46 @@ +# Example: Wails Desktop App Build Configuration +# Cross-platform desktop application with web frontend + +version: 1 + +project: + name: myapp + binary: myapp + +build: + main: . + env: + CGO_ENABLED: "1" # Required for Wails + ldflags: + - -s -w + - -X main.version={{.Version}} + +# Wails-specific configuration +wails: + frontend: ./frontend + # Auto-detects: npm, pnpm, yarn, bun + install_cmd: install + build_cmd: build + +targets: + # Desktop platforms only + - os: darwin + arch: amd64 + - os: darwin + arch: arm64 + - os: windows + arch: amd64 + - os: linux + arch: amd64 + +# Platform-specific packaging +package: + darwin: + - dmg + - app + windows: + - nsis + - zip + linux: + - tar.gz + - appimage diff --git a/docs/examples/build-linuxkit.yaml b/docs/examples/build-linuxkit.yaml new file mode 100644 index 00000000..75ebb191 --- /dev/null +++ b/docs/examples/build-linuxkit.yaml @@ -0,0 +1,33 @@ +# Example: LinuxKit Build Configuration +# Immutable Linux images + +version: 1 + +project: + name: myserver + type: linuxkit + +linuxkit: + config: .core/linuxkit/server.yml + + formats: + - iso # Bootable ISO (BIOS/EFI) + - qcow2 # QEMU/KVM/Proxmox + - raw # Raw disk image + - vmdk # VMware + - docker # Docker-loadable tarball + + platforms: + - linux/amd64 + - linux/arm64 + + # Output naming + name: "{{.Project}}-{{.Version}}" + +# The linuxkit config file (.core/linuxkit/server.yml) defines: +# - kernel version +# - init system +# - services to run +# - files to include +# +# See linuxkit-server.yml example diff --git a/docs/examples/build-minimal.yaml b/docs/examples/build-minimal.yaml new file mode 100644 index 00000000..9801947e --- /dev/null +++ b/docs/examples/build-minimal.yaml @@ -0,0 +1,7 @@ +# Example: Minimal Build Configuration +# Auto-detects everything from project structure + +version: 1 + +project: + name: myapp diff --git a/docs/examples/build-multi-binary.yaml b/docs/examples/build-multi-binary.yaml new file mode 100644 index 00000000..563a3579 --- /dev/null +++ b/docs/examples/build-multi-binary.yaml @@ -0,0 +1,51 @@ +# Example: Multi-Binary Build Configuration +# Multiple binaries from one repository + +version: 1 + +project: + name: mytools + +# Multiple build targets +builds: + - name: cli + binary: mytool + main: ./cmd/mytool + ldflags: + - -s -w + - -X main.version={{.Version}} + + - name: server + binary: myserver + main: ./cmd/server + ldflags: + - -s -w + - -X main.version={{.Version}} + + - name: worker + binary: myworker + main: ./cmd/worker + ldflags: + - -s -w + +# Shared settings +build: + env: + CGO_ENABLED: "0" + flags: + - -trimpath + +targets: + - os: linux + arch: amd64 + - os: linux + arch: arm64 + - os: darwin + arch: arm64 + +# Archive includes all binaries +archive: + format: tar.gz + files: + - LICENSE + - README.md diff --git a/docs/examples/build-php-laravel.yaml b/docs/examples/build-php-laravel.yaml new file mode 100644 index 00000000..ae23cadf --- /dev/null +++ b/docs/examples/build-php-laravel.yaml @@ -0,0 +1,50 @@ +# Example: PHP/Laravel Build Configuration +# FrankenPHP container with Laravel app + +version: 1 + +project: + name: mylaravel + type: php + +php: + version: "8.4" + + # Composer settings + composer: + install_args: + - --no-dev + - --optimize-autoloader + - --no-interaction + + # Frontend build + frontend: + enabled: true + build_cmd: "npm run build" + + # Octane configuration + octane: + server: frankenphp + workers: auto + max_requests: 500 + +# Docker output +docker: + dockerfile: Dockerfile + registry: ghcr.io + image: myorg/mylaravel + platforms: + - linux/amd64 + - linux/arm64 + tags: + - latest + - "{{.Version}}" + build_args: + PHP_VERSION: "8.4" + +# Optional: LinuxKit for immutable deployment +linuxkit: + config: .core/linuxkit/server-php.yml + formats: + - qcow2 + - iso