DEV Community: Pablo Lagos

🧊 How to Build a Fully Static Go Binary — Every Time (with go-builder and Docker)

Pablo Lagos — Sat, 28 Jun 2025 07:07:38 +0000

Want your Go app to “just run” on any Linux server, regardless of glibc?
You need real static linking — and it’s surprisingly easy to get wrong.

In this guide you’ll learn:

✅ Why CGO can break static builds
✅ How to cross-compile with musl
✅ How to do it inside Docker for guaranteed reproducibility
✅ How to declare all this in a clean .gobuilder.yml

⚙️ The problem: CGO and glibc versions

By default, Go wants to make static binaries. But the second you use CGO_ENABLED=1 (for SQLite, image processing, or networking optimizations), the linker pulls in your system’s libc — and suddenly you’ve got a dynamic dependency.

Run your binary on a server with an older glibc, and boom:

libc.so.6: version `GLIBC_2.32' not found

🫧 The solution: build with `musl` and force static linking

Musl is a lightweight C standard library designed for static builds.
Here’s the secret sauce:

CGO_ENABLED=1 CC=musl-gcc \
  go build -ldflags="-linkmode external -extldflags '-static'"

Check your binary:

file myapp   # should say: statically linked
ldd myapp    # should say: not a dynamic executable

✅ ✅ ✅

🗂️ Making this repeatable with `go-builder`

Manually remembering CGO_ENABLED, CC, and those scary -ldflags? Painful.
Let’s lock it down:

# .gobuilder.yml
build_dir: builds
source: ./cmd/myapp
output: myapp

env:
  CGO_ENABLED: "1"
  CC: musl-gcc

build:
  ldflags:
    - "-linkmode external -extldflags '-static'"
  vars:
    main.version: "${VERSION:-dev}"
  trimpath: true
  verify_static: true  # check with 'file' after build!

targets:
  - os: linux
    arch: amd64
  - os: linux
    arch: arm64

Run it:

VERSION=1.4.0 go-builder

✅ You get binaries under builds/linux/amd64/ and builds/linux/arm64/.
✅ If the linker produces a dynamic binary by mistake, the verify_static: true will fail the build.
✅ No bash scripts, no fragile Makefiles.

🐳 What if you don’t have `musl-gcc` installed?

Use a container with musl ready to go. Here’s a docker block in the same YAML:

docker:
  image: golang:1.23-alpine
  workdir: /src
  shell: sh
  setup:
    - apk add --no-cache musl-dev build-base git
  env:
    CGO_ENABLED: "1"
    CC: gcc # gcc is the name of musl-gcc in alpine

Now your build runs inside Alpine Linux, with musl preinstalled. The builds/ folder is shared with your host, so your static binaries are there immediately — no extra copy step.

Run:

go-builder

And your machine stays clean: no local musl toolchain needed.

🧪 Dry-run: double-check before wasting time

Want to see exactly what go-builder will run?

go-builder --dry-run

You’ll see:

Docker run command (if docker: is defined)
Environment variables
The go build line, with every tag, flag, and linker trick.

✅ Key takeaways

✔ musl makes true static linking predictable
✔ CGO_ENABLED=1 CC=musl-gcc + -extldflags '-static' are the magic trio
✔ verify_static: true guarantees your binary is really static
✔ Using Docker means zero “it works on my machine” moments
✔ go-builder locks your build config in YAML: repeatable, documented, and easy to share

🔗 Next steps

📄 Repo: github.com/pablolagos/go-builder
🧩 Install: go install github.com/pablolagos/go-builder@latest
⚡ --init writes a starter YAML, ready to tweak.

Stop chasing glibc errors. Ship one binary, run it anywhere.
Static linking can actually be fun.

Do you ship static Go binaries? Drop your tips below — I'd love to hear how you do it!

Fixing “GLIBC_x.x not found” in Go Binaries: Build Once, Run Anywhere

Pablo Lagos — Sat, 28 Jun 2025 06:55:43 +0000

“I built my shiny Go app. It works on my machine. But when I run it on a server — boom:
Error while loading shared libraries: libc.so.6: version 'GLIBC_2.32' not found.”_

Sound familiar? Let’s break down why this happens, what it means, and how you can prevent it every time.

🤔 Why does `GLIBC` bite you?

Go is famous for producing static binaries by default. But:

If your code (or a dependency) uses CGO, Go will link to your system’s C libraries.
On your dev machine, your libc might be GLIBC 2.35 (Ubuntu 22.04).
But your production machine could be older — say, GLIBC 2.28 (Debian 10).

Result? Your binary demands symbols that the older server’s libc doesn’t have.
No fancy containerization will fix that if the binary expects to find libc.so.6 on the host!

✔️ 3 ways to make this error disappear

✅ 1. Use a musl-based toolchain

Musl is a minimal C library that’s explicitly designed for static linking.

For example:

CGO_ENABLED=1 CC=x86_64-linux-musl-gcc \
  go build -ldflags="-linkmode external -extldflags '-static'"

Why this works:

You ship zero dynamic libc dependency.
Your binary works on any Linux kernel, no matter the host’s GLIBC version.

You can also build inside Alpine (which uses musl by default):

FROM golang:1.23-alpine

RUN apk add --no-cache musl-dev build-base

WORKDIR /src
COPY . .
RUN go build -tags netgo -ldflags="-linkmode external -extldflags '-static'" -o myapp ./cmd/myapp

✅ 2. Check that your binary is truly static

Don’t guess — verify!
Run file on the binary:

file myapp
# Should say: ELF 64-bit LSB executable, statically linked

Or check dynamic dependencies:

ldd myapp
# Should say: "not a dynamic executable"

If you see libc.so.6 in the list: your binary is not fully static!

✅ 3. Use a minimal base image or scratch

If you package your binary in a container, you don’t want to drag along a full glibc runtime just for your app.

Examples:

# Option A: static binary → scratch
FROM scratch
COPY myapp /myapp
ENTRYPOINT ["/myapp"]

# Option B: Alpine → musl → always works
FROM alpine:3.19
COPY myapp /usr/local/bin/myapp
ENTRYPOINT ["myapp"]

No glibc, no runtime version mismatch.

⚡ Gotchas: When you can’t be fully static

Some CGO dependencies can’t be statically linked easily (e.g., dynamic plugins, drivers, or certain SQLite features).
In these cases, match your build environment to your production environment: same glibc, same version, same distro.
Tools like Docker help, but musl or static linking is the long-term fix.

🧘 Stay sane: make it declarative

To avoid forgetting CGO_ENABLED, CC, or -extldflags, keep your build config versioned:

# .gobuilder.yml
env:
  CGO_ENABLED: "1"
  CC: gcc
build:
  ldflags:
    - "-linkmode external -extldflags '-static'"
  vars:
    main.version: "${VERSION}"
  tags: ["netgo"]

One file, repeatable builds, no surprises.

✅ Summary: one checklist for portable Go binaries

✔ Always verify: file and ldd
✔ Use musl + static linking when possible
✔ Test your binary on your oldest target environment
✔ Don’t depend on your dev machine’s glibc!

Next time you see “version GLIBC_2.xx not found”, you’ll know exactly what to do.

Happy compiling!
If you want a reproducible cross-build workflow with YAML and Docker baked in, check out go-builder — it keeps static linking predictable.

Creating users with SSH access only in Linux

Pablo Lagos — Wed, 04 Sep 2024 14:24:16 +0000

If we’re managing a Linux server and looking to enhance its security, a great step we can take is to create user accounts that can only log in using SSH keys, rather than relying on passwords.

This approach helps us protect against brute-force attacks and unauthorized access attempts that target weak or compromised passwords.

In this guide, we'll walk through the steps to create a new user with a home directory, and configure our server to allow login for this user exclusively through SSH key-based authentication.

By doing so, we’ll establish a more secure and reliable access method for our server.

1. Create the User with a Home Directory

Run the following command to create the user general with a home directory:

sudo useradd -m -s /bin/bash <username>

-m: Creates the home directory (/home/general).
-s /bin/bash: Sets /bin/bash as the default login shell for the user.

2. Configure SSH Key-Only Login

To disable password login and allow only SSH key-based access, follow these steps:

1. Lock the user's password to prevent password login:

sudo passwd -l <username>

This command locks the account for password-based login.

2. Set up SSH keys for the user:

Switch to the new user:

 sudo su - <username>

Create the .ssh directory in the user's home directory and set the correct permissions:

mkdir -p ~/.ssh
chmod 700 ~/.ssh

Create or copy the authorized_keys file with the allowed public SSH key and set the correct permissions:

touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Paste the public SSH key (e.g., id_rsa.pub) into the ~/.ssh/authorized_keys file.
Exit the general user:

exit

3. Verify SSH Configuration

Edit the SSH configuration file to ensure that SSH key authentication is allowed:

sudo nano /etc/ssh/sshd_config

Make sure you have the following settings:

PubkeyAuthentication yes

If the setting is commented #PubkeyAuthentication yes, it will work correctly, as the default value for PubkeyAuthentication is yes

If the PubkeyAuthentication was changed, save the changes and restart the SSH service:

sudo systemctl restart sshd

4. Test SSH Access

Now, try logging in with the new created user via SSH:

ssh <username>@server-ip -i path/to/private/key

You should only be able to log in if you have the private key corresponding to the public key set up in ~/.ssh/authorized_keys.

This completes the setup for the user to authenticate exclusively via SSH key!