File size: 19,824 Bytes
8baf122
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
---
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 Next.js 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 npx next build
RUN node scripts/fix-paths.js

# --- 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 Next.js 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 npx next build
RUN node scripts/fix-paths.js

# --- 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>