c-relay/docs/musl_static_build.md

MUSL Static Binary Build Guide

Overview

This guide explains how to build truly portable MUSL-based static binaries of c-relay using Alpine Linux Docker containers. These binaries have zero runtime dependencies and work on any Linux distribution.

Why MUSL?

MUSL vs glibc Static Binaries

MUSL Advantages:

• Truly Static: No hidden dependencies on system libraries
• Smaller Size: ~7.6MB vs ~12MB+ for glibc static builds
• Better Portability: Works on ANY Linux distribution without modification
• Cleaner Linking: No glibc-specific extensions or fortified functions
• Simpler Deployment: Single binary, no library compatibility issues

glibc Limitations:

• Static builds still require dynamic loading for NSS (Name Service Switch)
• Fortified functions (__*_chk) don't exist in MUSL
• Larger binary size due to glibc's complexity
• May have compatibility issues across different glibc versions

Build Process

Prerequisites

• Docker installed and running
• Sufficient disk space (~2GB for Docker layers)
• Internet connection (for downloading dependencies)

Quick Start

# Build MUSL static binary
./build_static.sh

# The binary will be created at:
# build/c_relay_static_musl_x86_64  (on x86_64)
# build/c_relay_static_musl_arm64   (on ARM64)

What Happens During Build

1. Alpine Linux Base: Uses Alpine 3.19 with native MUSL support

2. Static Dependencies: Builds all dependencies with static linking:

   • libsecp256k1 (Bitcoin cryptography)
   • libwebsockets (WebSocket server)
   • OpenSSL (TLS/crypto)
   • SQLite (database)
   • curl (HTTP client)
   • zlib (compression)

3. nostr_core_lib: Builds with MUSL-compatible flags:

   • Disables glibc fortification (-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0)
   • Includes required NIPs: 001, 006, 013, 017, 019, 044, 059
   • Produces static library (~316KB)

4. c-relay Compilation: Links everything statically:

   • All source files compiled with -static flag
   • Fortification disabled to avoid __*_chk symbols
   • Results in ~7.6MB stripped binary

5. Verification: Confirms binary is truly static:

   • ldd shows "not a dynamic executable"
   • file shows "statically linked"
   • Binary executes successfully

Technical Details

Dockerfile Structure

The build uses a multi-stage Dockerfile (Dockerfile.alpine-musl):

# Stage 1: Builder (Alpine Linux)
FROM alpine:3.19 AS builder
- Install build tools and static libraries
- Build dependencies from source
- Compile nostr_core_lib with MUSL flags
- Compile c-relay with full static linking
- Strip binary to reduce size

# Stage 2: Output (scratch)
FROM scratch AS output
- Contains only the final binary

Key Compilation Flags

For nostr_core_lib:

CFLAGS="-U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 -Wall -Wextra -std=c99 -fPIC -O2"

For c-relay:

gcc -static -O2 -Wall -Wextra -std=c99 \
    -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=0 \
    [source files] \
    -lwebsockets -lssl -lcrypto -lsqlite3 -lsecp256k1 \
    -lcurl -lz -lpthread -lm -ldl

Fortification Issue

Problem: GCC's -O2 optimization enables fortification by default, replacing standard functions with __*_chk variants (e.g., __snprintf_chk, __fprintf_chk). These are glibc-specific and don't exist in MUSL.

Solution: Explicitly disable fortification with:

• -U_FORTIFY_SOURCE (undefine any existing definition)
• -D_FORTIFY_SOURCE=0 (set to 0)

This must be applied to both nostr_core_lib and c-relay compilation.

NIP Dependencies

The build includes these NIPs in nostr_core_lib:

• NIP-001: Basic protocol (event creation, signing)
• NIP-006: Key derivation from mnemonic
• NIP-013: Proof of Work validation
• NIP-017: Private Direct Messages
• NIP-019: Bech32 encoding (nsec/npub)
• NIP-044: Modern encryption
• NIP-059: Gift Wrap (required by NIP-017)

Verification

Check Binary Type

# Should show "statically linked"
file build/c_relay_static_musl_x86_64

# Should show "not a dynamic executable"
ldd build/c_relay_static_musl_x86_64

# Check size (should be ~7.6MB)
ls -lh build/c_relay_static_musl_x86_64

Test Execution

# Show help
./build/c_relay_static_musl_x86_64 --help

# Show version
./build/c_relay_static_musl_x86_64 --version

# Run relay
./build/c_relay_static_musl_x86_64 --port 8888

Cross-Distribution Testing

Test the binary on different distributions to verify portability:

# Alpine Linux
docker run --rm -v $(pwd)/build:/app alpine:latest /app/c_relay_static_musl_x86_64 --version

# Ubuntu
docker run --rm -v $(pwd)/build:/app ubuntu:latest /app/c_relay_static_musl_x86_64 --version

# Debian
docker run --rm -v $(pwd)/build:/app debian:latest /app/c_relay_static_musl_x86_64 --version

# CentOS
docker run --rm -v $(pwd)/build:/app centos:latest /app/c_relay_static_musl_x86_64 --version

Troubleshooting

Docker Permission Denied

Problem: permission denied while trying to connect to the Docker daemon socket

Solution: Add user to docker group:

sudo usermod -aG docker $USER
newgrp docker  # Or logout and login again

Build Fails with Fortification Errors

Problem: undefined reference to '__snprintf_chk' or '__fprintf_chk'

Solution: Ensure fortification is disabled in both:

1. nostr_core_lib build.sh (line 534)
2. c-relay compilation flags in Dockerfile

Binary Won't Execute

Problem: Binary fails to run on target system

Checks:

1. Verify it's truly static: ldd binary should show "not a dynamic executable"
2. Check architecture matches: file binary should show correct arch
3. Ensure execute permissions: chmod +x binary

Missing NIP Functions

Problem: undefined reference to 'nostr_nip*' during linking

Solution: Add missing NIPs to the build command:

./build.sh --nips=1,6,13,17,19,44,59

Deployment

Single Binary Deployment

# Copy binary to server
scp build/c_relay_static_musl_x86_64 user@server:/opt/c-relay/

# Run on server (no dependencies needed!)
ssh user@server
cd /opt/c-relay
./c_relay_static_musl_x86_64 --port 8888

SystemD Service

[Unit]
Description=C-Relay Nostr Relay (MUSL Static)
After=network.target

[Service]
Type=simple
User=c-relay
WorkingDirectory=/opt/c-relay
ExecStart=/opt/c-relay/c_relay_static_musl_x86_64
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Performance Comparison

Metric	MUSL Static	glibc Static	glibc Dynamic
Binary Size	7.6 MB	12+ MB	2-3 MB
Startup Time	~50ms	~60ms	~40ms
Memory Usage	Similar	Similar	Similar
Portability	✓ Any Linux	⚠ glibc only	✗ Requires libs
Dependencies	None	NSS libs	Many libs

Best Practices

1. Always verify the binary is truly static before deployment
2. Test on multiple distributions to ensure portability
3. Keep Docker images updated for security patches
4. Document the build date and commit hash for reproducibility
5. Store binaries with architecture in filename (e.g., _x86_64, _arm64)

References

• MUSL libc
• Alpine Linux
• Static Linking Best Practices
• GCC Fortification

Changelog

2025-10-11

• Initial MUSL build system implementation
• Alpine Docker-based build process
• Fortification fix for nostr_core_lib
• Complete NIP dependency resolution
• Documentation created