706 lines
19 KiB
Plaintext
706 lines
19 KiB
Plaintext
---
|
|
title: "Building Dynamically Linked Bifrost Binary"
|
|
description: "Learn how to build a dynamically linked Bifrost binary required for custom plugin support"
|
|
icon: "hammer"
|
|
---
|
|
|
|
## Why Dynamic Linking?
|
|
|
|
Go's plugin system requires **dynamic linking** to load `.so` files at runtime. By default, Bifrost builds are **statically linked** for maximum portability across Linux distributions - they bundle all dependencies including the C standard library (libc). However, statically linked binaries **cannot load Go plugins**.
|
|
|
|
To use custom plugins with Bifrost, you must build a dynamically linked binary that links against the system's libc at runtime.
|
|
|
|
<Warning>
|
|
Dynamic plugins only work on **Linux** and **macOS** (Darwin). Windows is not supported by Go's plugin system.
|
|
</Warning>
|
|
|
|
## Static vs Dynamic Builds
|
|
|
|
### Static Builds (Default)
|
|
|
|
Bifrost's default build configuration creates statically linked binaries:
|
|
|
|
```bash
|
|
go build \
|
|
-ldflags="-w -s -extldflags '-static' -X main.Version=v1.3.30" \
|
|
-tags "sqlite_static" \
|
|
-o bifrost-http
|
|
```
|
|
|
|
**Characteristics:**
|
|
- ✅ Portable across all Linux distributions (musl, glibc, etc.)
|
|
- ✅ No external dependencies required at runtime
|
|
- ✅ Smaller deployment surface area
|
|
- ❌ **Cannot load Go plugins**
|
|
|
|
**Use static builds when:** You don't need custom plugins and want maximum portability.
|
|
|
|
### Dynamic Builds (For Plugins)
|
|
|
|
To enable plugin support, build without static linking flags:
|
|
|
|
```bash
|
|
go build \
|
|
-ldflags="-w -s -X main.Version=v1.3.30" \
|
|
-o bifrost-http
|
|
```
|
|
|
|
**Characteristics:**
|
|
- ✅ **Can load Go plugins** (`.so` files)
|
|
- ✅ Slightly faster compilation
|
|
- ⚠️ Must match the target system's libc (musl vs glibc)
|
|
- ⚠️ Less portable across different Linux distributions
|
|
|
|
**Use dynamic builds when:** You need custom plugin support.
|
|
|
|
## Building with Makefile
|
|
|
|
The easiest way to build a dynamic binary is using the `DYNAMIC=1` flag with the Makefile:
|
|
|
|
### Local Build
|
|
|
|
```bash
|
|
# Build dynamically linked binary for your current platform
|
|
make build DYNAMIC=1
|
|
|
|
# With version tag
|
|
make build DYNAMIC=1 VERSION=1.3.30
|
|
```
|
|
|
|
This creates `tmp/bifrost-http` as a dynamically linked binary.
|
|
|
|
### Cross-Compilation
|
|
|
|
```bash
|
|
# Build for Linux AMD64 (uses Docker if cross-compiling)
|
|
make build DYNAMIC=1 GOOS=linux GOARCH=amd64
|
|
|
|
# Build for Linux ARM64
|
|
make build DYNAMIC=1 GOOS=linux GOARCH=arm64
|
|
```
|
|
|
|
### How It Works
|
|
|
|
The `DYNAMIC=1` flag automatically:
|
|
- ✅ Removes `-extldflags "-static"` from ldflags
|
|
- ✅ Removes `-tags "sqlite_static"` build tag
|
|
- ✅ Keeps `CGO_ENABLED=1` (required for SQLite and plugins)
|
|
- ✅ Uses Docker for cross-compilation when needed
|
|
|
|
## Building with Docker
|
|
|
|
For containerized deployments, you'll need to modify the Dockerfile. Here are two complete examples based on your target environment's libc.
|
|
|
|
### Option A: Alpine Linux (musl libc)
|
|
|
|
Use this for Alpine-based deployments or when you want minimal image size.
|
|
|
|
<Accordion title="Complete Dockerfile for Alpine (musl libc)">
|
|
|
|
```dockerfile
|
|
# --- UI Build Stage: Build the React + Vite frontend ---
|
|
FROM node:25-alpine3.23 AS ui-builder
|
|
WORKDIR /app
|
|
|
|
# Copy UI package files and install dependencies
|
|
COPY ui/package*.json ./
|
|
RUN npm ci
|
|
|
|
# Copy UI source code
|
|
COPY ui/ ./
|
|
|
|
# Build UI (skip the copy-build step)
|
|
RUN npm run build-enterprise
|
|
|
|
# --- Go Build Stage: Compile the Go binary ---
|
|
FROM golang:1.26.1-alpine3.23 AS builder
|
|
WORKDIR /app
|
|
|
|
# Install dependencies including gcc for CGO and sqlite
|
|
RUN apk add --no-cache gcc musl-dev sqlite-dev
|
|
|
|
# Set environment for CGO-enabled build (required for go-sqlite3 and plugins)
|
|
ENV CGO_ENABLED=1 GOOS=linux
|
|
|
|
COPY transports/go.mod transports/go.sum ./
|
|
RUN go mod download
|
|
|
|
# Copy source code and dependencies
|
|
COPY transports/ ./
|
|
|
|
COPY --from=ui-builder /app/out ./bifrost-http/ui
|
|
|
|
# Build the binary with CGO enabled for DYNAMIC LINKING
|
|
ENV GOWORK=off
|
|
ARG VERSION=unknown
|
|
RUN go build \
|
|
-ldflags="-w -s -X main.Version=v${VERSION}" \
|
|
-a -trimpath \
|
|
-o /app/main \
|
|
./bifrost-http
|
|
|
|
# Verify build succeeded
|
|
RUN test -f /app/main || (echo "Build failed" && exit 1)
|
|
|
|
# --- Runtime Stage: Minimal runtime image ---
|
|
FROM alpine:3.23
|
|
WORKDIR /app
|
|
|
|
# Install runtime dependencies for CGO-enabled dynamic binary
|
|
# musl: C standard library (required for CGO binaries)
|
|
# libgcc: GCC runtime library
|
|
# ca-certificates: For HTTPS connections
|
|
# wget: For healthcheck
|
|
RUN apk add --no-cache musl libgcc ca-certificates wget
|
|
|
|
# Create data directory and set up user
|
|
COPY --from=builder /app/main .
|
|
COPY --from=builder /app/docker-entrypoint.sh .
|
|
|
|
# Getting arguments
|
|
ARG ARG_APP_PORT=8080
|
|
ARG ARG_APP_HOST=0.0.0.0
|
|
ARG ARG_LOG_LEVEL=info
|
|
ARG ARG_LOG_STYLE=json
|
|
ARG ARG_APP_DIR=/app/data
|
|
|
|
# Environment variables with defaults (can be overridden at runtime)
|
|
ENV APP_PORT=$ARG_APP_PORT \
|
|
APP_HOST=$ARG_APP_HOST \
|
|
LOG_LEVEL=$ARG_LOG_LEVEL \
|
|
LOG_STYLE=$ARG_LOG_STYLE \
|
|
APP_DIR=$ARG_APP_DIR
|
|
|
|
RUN mkdir -p $APP_DIR/logs && \
|
|
adduser -D -s /bin/sh appuser && \
|
|
chown -R appuser:appuser /app && \
|
|
chmod +x /app/docker-entrypoint.sh
|
|
USER appuser
|
|
|
|
# Declare volume for data persistence
|
|
VOLUME ["/app/data"]
|
|
EXPOSE $APP_PORT
|
|
|
|
# Health check for container status monitoring
|
|
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
|
CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:${APP_PORT}/metrics || exit 1
|
|
|
|
# Use entrypoint script that handles volume permissions and argument processing
|
|
ENTRYPOINT ["/app/docker-entrypoint.sh"]
|
|
CMD ["/app/main"]
|
|
```
|
|
|
|
</Accordion>
|
|
|
|
**Key changes from static build:**
|
|
- Line 40-44: Removed `-extldflags '-static'` and `-tags "sqlite_static"`
|
|
- Removed UPX compression step (optional, but simpler)
|
|
- Runtime uses musl libc from Alpine base image
|
|
|
|
**Build and run:**
|
|
|
|
```bash
|
|
# Build the image
|
|
docker build -f transports/Dockerfile -t bifrost:dynamic-alpine .
|
|
|
|
# Run the container
|
|
docker run -p 8080:8080 -v ./plugins:/app/data/plugins bifrost:dynamic-alpine
|
|
```
|
|
|
|
### Option B: Debian (glibc)
|
|
|
|
Use this for Debian/Ubuntu-based deployments or when deploying to glibc-based systems.
|
|
|
|
<Accordion title="Complete Dockerfile for Debian (glibc)">
|
|
|
|
```dockerfile
|
|
# --- UI Build Stage: Build the React + Vite frontend ---
|
|
FROM node:25-bookworm AS ui-builder
|
|
WORKDIR /app
|
|
|
|
# Copy UI package files and install dependencies
|
|
COPY ui/package*.json ./
|
|
RUN npm ci
|
|
|
|
# Copy UI source code
|
|
COPY ui/ ./
|
|
|
|
# Build UI
|
|
RUN npm run build-enterprise
|
|
|
|
# --- Go Build Stage: Compile the Go binary ---
|
|
FROM golang:1.26.1-bookworm AS builder
|
|
WORKDIR /app
|
|
|
|
# Install dependencies including gcc for CGO and sqlite
|
|
RUN apt-get update && apt-get install -y \
|
|
gcc \
|
|
libc6-dev \
|
|
libsqlite3-dev \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
|
|
# Set environment for CGO-enabled build (required for go-sqlite3 and plugins)
|
|
ENV CGO_ENABLED=1 GOOS=linux
|
|
|
|
COPY transports/go.mod transports/go.sum ./
|
|
RUN go mod download
|
|
|
|
# Copy source code and dependencies
|
|
COPY transports/ ./
|
|
|
|
COPY --from=ui-builder /app/out ./bifrost-http/ui
|
|
|
|
# Build the binary with CGO enabled for DYNAMIC LINKING
|
|
ENV GOWORK=off
|
|
ARG VERSION=unknown
|
|
RUN go build \
|
|
-ldflags="-w -s -X main.Version=v${VERSION}" \
|
|
-a -trimpath \
|
|
-o /app/main \
|
|
./bifrost-http
|
|
|
|
# Verify build succeeded
|
|
RUN test -f /app/main || (echo "Build failed" && exit 1)
|
|
|
|
# --- Runtime Stage: Minimal runtime image ---
|
|
FROM debian:bookworm-slim
|
|
WORKDIR /app
|
|
|
|
# Install runtime dependencies for CGO-enabled dynamic binary
|
|
# libc6: GNU C Library (required for glibc-linked binaries)
|
|
# ca-certificates: For HTTPS connections
|
|
RUN apt-get update && apt-get install -y \
|
|
libc6 \
|
|
ca-certificates \
|
|
wget \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
|
|
# Create data directory and set up user
|
|
COPY --from=builder /app/main .
|
|
COPY --from=builder /app/docker-entrypoint.sh .
|
|
|
|
# Getting arguments
|
|
ARG ARG_APP_PORT=8080
|
|
ARG ARG_APP_HOST=0.0.0.0
|
|
ARG ARG_LOG_LEVEL=info
|
|
ARG ARG_LOG_STYLE=json
|
|
ARG ARG_APP_DIR=/app/data
|
|
|
|
# Environment variables with defaults (can be overridden at runtime)
|
|
ENV APP_PORT=$ARG_APP_PORT \
|
|
APP_HOST=$ARG_APP_HOST \
|
|
LOG_LEVEL=$ARG_LOG_LEVEL \
|
|
LOG_STYLE=$ARG_LOG_STYLE \
|
|
APP_DIR=$ARG_APP_DIR
|
|
|
|
RUN mkdir -p $APP_DIR/logs && \
|
|
useradd -m -s /bin/sh appuser && \
|
|
chown -R appuser:appuser /app && \
|
|
chmod +x /app/docker-entrypoint.sh
|
|
USER appuser
|
|
|
|
# Declare volume for data persistence
|
|
VOLUME ["/app/data"]
|
|
EXPOSE $APP_PORT
|
|
|
|
# Health check for container status monitoring
|
|
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
|
|
CMD wget --no-verbose --tries=1 --spider http://127.0.0.1:${APP_PORT}/metrics || exit 1
|
|
|
|
# Use entrypoint script that handles volume permissions and argument processing
|
|
ENTRYPOINT ["/app/docker-entrypoint.sh"]
|
|
CMD ["/app/main"]
|
|
```
|
|
|
|
</Accordion>
|
|
|
|
**Key differences from Alpine version:**
|
|
- Uses `bookworm` (Debian 12) base images instead of Alpine
|
|
- Installs `apt` packages instead of `apk`
|
|
- Runtime uses glibc (libc6) instead of musl
|
|
- Uses `useradd` instead of `adduser` for user creation
|
|
|
|
**Build and run:**
|
|
|
|
```bash
|
|
# Build the image
|
|
docker build -f transports/Dockerfile.debian -t bifrost:dynamic-debian .
|
|
|
|
# Run the container
|
|
docker run -p 8080:8080 -v ./plugins:/app/data/plugins bifrost:dynamic-debian
|
|
```
|
|
|
|
## libc Compatibility
|
|
|
|
Understanding libc (C standard library) compatibility is **critical** when building dynamic binaries and plugins.
|
|
|
|
### musl vs glibc
|
|
|
|
Linux distributions use one of two main C standard libraries:
|
|
|
|
| libc Type | Used By | Characteristics |
|
|
|-----------|---------|-----------------|
|
|
| **musl** | Alpine Linux | Lightweight, minimal, security-focused |
|
|
| **glibc** | Debian, Ubuntu, RHEL, CentOS, Fedora, Amazon Linux | Standard GNU C Library, feature-rich |
|
|
|
|
### The Golden Rule
|
|
|
|
<Warning>
|
|
- **A binary built with musl will NOT run on glibc systems.**
|
|
- **A binary built with glibc will NOT run on musl systems.**
|
|
- **Plugins and Bifrost MUST use the same libc.**
|
|
</Warning>
|
|
|
|
### Why This Matters
|
|
|
|
When you build a dynamic binary:
|
|
|
|
```bash
|
|
# Built on Alpine (musl)
|
|
$ ldd bifrost-http
|
|
linux-vdso.so.1
|
|
libc.musl-x86_64.so.1 => /lib/ld-musl-x86_64.so.1
|
|
|
|
# Built on Debian (glibc)
|
|
$ ldd bifrost-http
|
|
linux-vdso.so.1
|
|
libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6
|
|
```
|
|
|
|
The binary is linked to a **specific** libc implementation. If you try to run it on a system with a different libc, you'll get errors like:
|
|
|
|
```
|
|
error while loading shared libraries: libc.musl-x86_64.so.1: cannot open shared object file
|
|
```
|
|
|
|
### Choosing Your Build Environment
|
|
|
|
**Decision Matrix:**
|
|
|
|
| Target Deployment | Build With | Dockerfile Base |
|
|
|-------------------|------------|-----------------|
|
|
| Alpine containers | musl | `golang:1.26.1-alpine3.23` |
|
|
| Debian/Ubuntu containers | glibc | `golang:1.26.1-bookworm` |
|
|
| Ubuntu/Debian servers | glibc | `golang:1.26.1-bookworm` |
|
|
| RHEL/CentOS servers | glibc | Native build or glibc container |
|
|
| Kubernetes (Alpine) | musl | `golang:1.26.1-alpine3.23` |
|
|
| Kubernetes (Debian) | glibc | `golang:1.26.1-bookworm` |
|
|
|
|
**Simple rule:** Build with the same base OS family as your deployment target.
|
|
|
|
### Building Plugins
|
|
|
|
Plugins **must** be built with the **exact same environment** as your Bifrost binary:
|
|
|
|
```bash
|
|
# If Bifrost was built with Alpine/musl
|
|
docker run --rm \
|
|
-v "$PWD:/work" \
|
|
-w /work \
|
|
golang:1.26.1-alpine3.23 \
|
|
sh -c "apk add --no-cache gcc musl-dev && \
|
|
go build -buildmode=plugin -o myplugin.so main.go"
|
|
|
|
# If Bifrost was built with Debian/glibc
|
|
docker run --rm \
|
|
-v "$PWD:/work" \
|
|
-w /work \
|
|
golang:1.26.1-bookworm \
|
|
sh -c "apt-get update && apt-get install -y gcc && \
|
|
go build -buildmode=plugin -o myplugin.so main.go"
|
|
```
|
|
|
|
See the [hello-world plugin Makefile](https://github.com/maximhq/bifrost/blob/main/examples/plugins/hello-world/Makefile) for a complete example.
|
|
|
|
## Verification
|
|
|
|
### Verify Dynamic Linking
|
|
|
|
After building, check that your binary is dynamically linked:
|
|
|
|
```bash
|
|
# Check binary dependencies
|
|
ldd tmp/bifrost-http
|
|
|
|
# Expected output (musl):
|
|
linux-vdso.so.1
|
|
libc.musl-x86_64.so.1 => /lib/ld-musl-x86_64.so.1
|
|
|
|
# Expected output (glibc):
|
|
linux-vdso.so.1
|
|
libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6
|
|
libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0
|
|
```
|
|
|
|
If you see `statically linked`, the binary **will not load plugins**.
|
|
|
|
### Verify Plugin Compatibility
|
|
|
|
Test that your plugin loads successfully:
|
|
|
|
```bash
|
|
# Start Bifrost with your plugin configured
|
|
./tmp/bifrost-http -config config.json
|
|
|
|
# Check logs for plugin initialization
|
|
# Should see: "Plugin loaded successfully: your-plugin-name"
|
|
```
|
|
|
|
## Go Version and Package Compatibility
|
|
|
|
### Go Version Requirement
|
|
|
|
Bifrost is built with **Go 1.26.1**. Your plugin **must** be compiled with the exact same Go version to ensure compatibility.
|
|
|
|
```bash
|
|
# Check your Go version
|
|
go version
|
|
# Should output: go version go1.26.1 ...
|
|
|
|
# If you need to install Go 1.26.1
|
|
# Visit: https://go.dev/dl/
|
|
```
|
|
|
|
### Key Package Versions
|
|
|
|
Bifrost uses the following key packages across its three main modules that may affect plugin development:
|
|
|
|
#### Transport Layer (`transports/go.mod`)
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `github.com/bytedance/sonic` | v1.14.1 | High-performance JSON serialization |
|
|
| `github.com/valyala/fasthttp` | v1.67.0 | Fast HTTP server/client |
|
|
| `github.com/fasthttp/router` | v1.5.4 | HTTP router for fasthttp |
|
|
| `github.com/fasthttp/websocket` | v1.5.12 | WebSocket support |
|
|
| `github.com/prometheus/client_golang` | v1.23.0 | Prometheus metrics |
|
|
| `gorm.io/gorm` | v1.31.1 | Database ORM |
|
|
|
|
#### Core Layer (`core/go.mod`)
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `github.com/bytedance/sonic` | v1.14.1 | High-performance JSON serialization |
|
|
| `github.com/valyala/fasthttp` | v1.67.0 | Fast HTTP client for providers |
|
|
| `github.com/google/uuid` | v1.6.0 | UUID generation |
|
|
| `github.com/rs/zerolog` | v1.34.0 | Zero-allocation JSON logger |
|
|
| `github.com/mark3labs/mcp-go` | v0.41.1 | Model Context Protocol support |
|
|
| `golang.org/x/oauth2` | v0.32.0 | OAuth2 client |
|
|
|
|
#### Framework Layer (`framework/go.mod`)
|
|
|
|
| Package | Version | Purpose |
|
|
|---------|---------|---------|
|
|
| `github.com/redis/go-redis/v9` | v9.14.0 | Redis client for caching |
|
|
| `github.com/weaviate/weaviate-go-client/v5` | v5.5.0 | Weaviate vector store client |
|
|
| `github.com/mattn/go-sqlite3` | v1.14.32 | SQLite3 driver (requires CGO) |
|
|
| `gorm.io/gorm` | v1.31.1 | Database ORM |
|
|
| `gorm.io/driver/sqlite` | v1.6.0 | GORM SQLite driver |
|
|
| `gorm.io/driver/postgres` | v1.6.0 | GORM PostgreSQL driver |
|
|
| `golang.org/x/crypto` | v0.43.0 | Cryptographic functions |
|
|
|
|
<Note>
|
|
If your plugin imports any of these packages, use compatible versions to avoid runtime issues. Check `transports/go.mod`, `core/go.mod`, and `framework/go.mod` for complete dependency lists.
|
|
</Note>
|
|
|
|
### Checking Bifrost's Dependencies
|
|
|
|
To see all dependencies used by Bifrost across its three main modules:
|
|
|
|
```bash
|
|
# View transport layer dependencies
|
|
cat transports/go.mod
|
|
|
|
# View core dependencies
|
|
cat core/go.mod
|
|
|
|
# View framework dependencies
|
|
cat framework/go.mod
|
|
|
|
# Or list all dependencies for a specific module
|
|
cd transports && go list -m all
|
|
cd ../core && go list -m all
|
|
cd ../framework && go list -m all
|
|
```
|
|
|
|
### Plugin go.mod Example
|
|
|
|
When creating a plugin, your `go.mod` should match Bifrost's Go version:
|
|
|
|
```go
|
|
module github.com/example/my-plugin
|
|
|
|
go 1.26.1
|
|
|
|
require (
|
|
github.com/maximhq/bifrost/core v1.2.38
|
|
// Optional: Add framework for advanced features
|
|
// github.com/maximhq/bifrost/framework v1.1.48
|
|
|
|
// Add other dependencies as needed, matching versions from Bifrost's go.mod files
|
|
// github.com/bytedance/sonic v1.14.1
|
|
// github.com/rs/zerolog v1.34.0
|
|
)
|
|
```
|
|
|
|
<Tip>
|
|
Import only the Bifrost modules you need. Most plugins only require `core`. Use `framework` if you need access to config stores, vector stores, or other framework features.
|
|
</Tip>
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Errors
|
|
|
|
#### 1. Cannot load plugin - Go version mismatch
|
|
|
|
```
|
|
cannot load plugin: plugin was built with a different version of package runtime/internal/sys
|
|
```
|
|
|
|
**Cause:** Plugin and Bifrost were built with different Go versions.
|
|
|
|
**Solution:** Use the exact same Go version (Go 1.26.1) for both:
|
|
|
|
```bash
|
|
# Check Go version used for Bifrost
|
|
./tmp/bifrost-http -version
|
|
|
|
# Verify your Go version matches
|
|
go version # Should output: go version go1.26.1
|
|
|
|
# See full compatibility requirements
|
|
```
|
|
|
|
Refer to [Go Version and Package Compatibility](#go-version-and-package-compatibility) for details.
|
|
|
|
#### 2. Shared library not found
|
|
|
|
```
|
|
error while loading shared libraries: libc.musl-x86_64.so.1: cannot open shared object file
|
|
```
|
|
|
|
**Cause:** Binary built with musl trying to run on glibc system (or vice versa).
|
|
|
|
**Solution:** Rebuild with the correct libc for your target system.
|
|
|
|
#### 3. Plugin architecture mismatch
|
|
|
|
```
|
|
plugin was built with a different version of package internal/cpu
|
|
```
|
|
|
|
**Cause:** Plugin and Bifrost built for different architectures (amd64 vs arm64).
|
|
|
|
**Solution:** Ensure `GOARCH` matches for both builds:
|
|
|
|
```bash
|
|
# Check architecture
|
|
uname -m # x86_64 = amd64, aarch64 = arm64
|
|
|
|
# Build with explicit architecture
|
|
GOARCH=amd64 go build ...
|
|
```
|
|
|
|
#### 4. Plugin file not found
|
|
|
|
```
|
|
plugin.Open("myplugin.so"): realpath failed: no such file or directory
|
|
```
|
|
|
|
**Cause:** Plugin file path is incorrect in config.
|
|
|
|
**Solution:** Use absolute paths or verify relative paths:
|
|
|
|
```json
|
|
{
|
|
"plugins": [
|
|
{
|
|
"path": "/app/data/plugins/myplugin.so",
|
|
"config": {}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 1. Document Your Build Environment
|
|
|
|
Create a `BUILD.md` file documenting:
|
|
- Go version used
|
|
- Base image (Alpine vs Debian)
|
|
- Build commands
|
|
- Target deployment platform
|
|
|
|
### 2. Use Consistent Tooling
|
|
|
|
Match Bifrost's exact Go version and key dependencies (see [Go Version and Package Compatibility](#go-version-and-package-compatibility)):
|
|
|
|
```bash
|
|
# Pin Go version in Dockerfile
|
|
FROM golang:1.26.1-alpine3.23 AS builder
|
|
|
|
# Pin Go version in Makefile/CI
|
|
GO_VERSION=1.26.1
|
|
```
|
|
|
|
### 3. Test Plugin Loading Locally
|
|
|
|
Before deploying, test plugin loading:
|
|
|
|
```bash
|
|
# Build both Bifrost and plugin
|
|
make build DYNAMIC=1
|
|
cd examples/plugins/hello-world && make build
|
|
|
|
# Test loading
|
|
./tmp/bifrost-http -config examples/plugins/hello-world/config.json
|
|
```
|
|
|
|
### 4. Version Your Plugins
|
|
|
|
Tag plugin builds with version and build info:
|
|
|
|
```bash
|
|
go build -buildmode=plugin \
|
|
-ldflags="-X main.Version=v1.0.0 -X main.BuildTime=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
|
|
-o myplugin-v1.0.0.so
|
|
```
|
|
|
|
### 5. Multi-Stage Dockerfiles for Plugins
|
|
|
|
Build plugins in the same Dockerfile as Bifrost:
|
|
|
|
```dockerfile
|
|
# Build plugin
|
|
FROM golang:1.26.1-alpine3.23 AS plugin-builder
|
|
WORKDIR /plugin
|
|
COPY plugins/myplugin/ .
|
|
RUN apk add --no-cache gcc musl-dev && \
|
|
go build -buildmode=plugin -o myplugin.so main.go
|
|
|
|
# Build Bifrost
|
|
FROM golang:1.26.1-alpine3.23 AS bifrost-builder
|
|
# ... (bifrost build steps)
|
|
|
|
# Runtime
|
|
FROM alpine:3.23
|
|
COPY --from=bifrost-builder /app/main .
|
|
COPY --from=plugin-builder /plugin/myplugin.so /app/plugins/
|
|
```
|
|
|
|
This ensures plugins and Bifrost use identical build environments.
|
|
|
|
## Next Steps
|
|
|
|
Now that you have a dynamically linked Bifrost binary:
|
|
|
|
1. **[Write your first plugin](./writing-plugin)** - Learn the plugin API and create custom functionality
|
|
2. **[Deploy with plugins](../deployment-guides)** - Best practices for production deployments
|
|
3. **[Example plugins](https://github.com/maximhq/bifrost/tree/main/examples/plugins)** - Study working examples
|
|
|
|
<Note>
|
|
For questions or issues with dynamic builds and plugins, visit our [GitHub Discussions](https://github.com/maximhq/bifrost/discussions) or [Discord community](https://discord.gg/exN5KAydbU).
|
|
</Note>
|
|
|