English
Quick Start Guide to Packaging RPMs for Go Services on macOS

Scope of This Article: Quick Start
This is a quick-start article with a single goal: help you, in the shortest possible time, successfully build an installable RPM package for a Go service on macOS and verify that it works. It therefore covers only the main path — no multi-package management, dependency declarations, package signing, parallel multi-architecture builds, CI/CD integration, or other advanced topics.
If you've already done one successful pass and want to see the more production-oriented approach (directory conventions used in real projects, scripted builds, versioning and artifact management, coordination with canary releases, and more), I'll be writing a separate article on real-world project practices and actionable tips, with a link added at the end of this post once it's published.
When you develop a Go service on macOS and ultimately deploy it to Linux servers, you'll often need to package it as an RPM. This article recommends the nFPM approach — written in pure Go, zero rpmbuild dependency, fast installation, and simple configuration. It also records a real pitfall with brew install rpm and FPM on macOS 13: a source build that still hadn't finished after an hour and a half. Finally, it offers a Docker fallback.
Choosing an Approach: Why nFPM Is the Recommendation
| Approach | Dependencies | Experience on macOS 13 | Recommendation |
|---|---|---|---|
| nFPM | Pure-Go binary, no rpmbuild | Fast install, no source build | ⭐⭐⭐⭐⭐ Top pick |
| FPM + brew rpm | Ruby + rpmbuild toolchain | Triggers massive source builds, unpredictable time | ⭐⭐ Backup |
| Docker + FPM | Docker Desktop | Clean environment, slow first image pull | ⭐⭐⭐⭐ Backup |
nFPM is a pure-Go packager maintained by the GoReleaser team. It writes RPM format directly and never invokes rpmbuild, so it won't pull in the whole Linux toolchain of openssl, rust, llvm, and so on. That's its core advantage on your machine.
Step 1: Cross-Compile the Go Service into a Linux Binary
nFPM doesn't handle compilation, so you need to cross-compile manually first. For a pure-Go project (no CGO dependency), the command is simple:
bash
# Compile a static binary for Linux amd64
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o my-service ./cmd/server
chmod +x my-serviceNote: Keeping
CGO_ENABLED=0produces a static binary that runs on any Linux distribution without glibc version issues. If your project depends on CGO (e.g., sqlite3), cross-compilation becomes much more complex and requires additional toolchains.
Step 2: Prepare the systemd Service File
If you want the RPM to be manageable via systemctl after installation, prepare a .service file:
ini
# my-service.service
[Unit]
Description=My Go Service
After=network.target
[Service]
Type=simple
User=my-service
WorkingDirectory=/usr/local/bin
ExecStart=/usr/local/bin/my-service
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.targetStep 3: Install nFPM
The recommended way is GoReleaser's tap, which provides the latest version:
bash
brew install goreleaser/tap/nfpmIf you don't mind a slightly older version, you can also use the Homebrew core repository version (faster to install):
bash
brew install nfpmVerify the installation:
bash
nfpm --versionAlternative: If brew installation also hits bottle issues, you can install directly with Go — it only compiles nFPM itself, with very few dependencies:
bashgo install github.com/goreleaser/nfpm/v2/cmd/nfpm@latest
Step 4: Write nfpm.yaml
Assume the following directory structure:
.
├── my-service # Cross-compiled Linux binary
├── my-service.service # systemd service file
└── nfpm.yamlCreate nfpm.yaml:
yaml
name: my-service
arch: amd64
platform: linux
version: 1.0.0
release: "1"
section: default
priority: extra
maintainer: [email protected]
description: My Go Service
vendor: YourName
homepage: https://example.com
contents:
- src: ./my-service
dst: /usr/local/bin/my-service
file_info:
mode: 0755
- src: ./my-service.service
dst: /usr/lib/systemd/system/my-service.service
file_info:
mode: 0644Key points:
mode: 0755ensures the binary has execute permission (nFPM won't add the executable bit automatically)platform: linuxandarch: amd64must matchGOOS/GOARCH; for ARM targets, change toarch: arm64versionandreleasetogether form the RPM version number1.0.0-1
Step 5: Generate and Verify the RPM
Generate with a single command:
bash
nfpm pkg --packager rpm --target .This produces my-service-1.0.0.x86_64.rpm in the current directory. --target . means output to the current directory.
Verify the package contents (requires the rpm command locally; not having it doesn't affect nFPM packaging):
bash
rpm -qpl my-service-1.0.0.x86_64.rpmYou should see /usr/local/bin/my-service and /usr/lib/systemd/system/my-service.service.
Pitfall Log: The Nightmare of brew install rpm on macOS 13
Before switching to nFPM, I first tried the FPM approach, which required brew install rpm to supply rpmbuild. On macOS 13, I ran into the following problems:
1. Homebrew no longer provides pre-built bottles for old macOS versions
The log clearly warned:
Warning: You are using macOS 13.
We (and Apple) do not provide support for this old version.
Homebrew no longer builds bottles for this configuration.This means every dependency has to be compiled from source.
2. It triggers a source build of the entire Linux toolchain
rpm has a great many dependencies: openssl@4, rust, llvm, [email protected], gettext, libunistring, lz4, pkgconf, json-c, and more. The log showed libunistring alone taking 14 minutes, gettext 19 minutes, and openssl@4 12 minutes — an hour and a half later it still hadn't finished installing.
3. Link conflicts
Error: The `brew link` step did not complete successfully
Could not symlink bin/pkg-config
Target /usr/local/bin/pkg-config already exists.You have to manually run brew link --overwrite pkgconf to resolve it.
4. Xcode and Command Line Tools are too old
The log repeatedly warned that Xcode 14.3 is too old and Command Line Tools need updating, further slowing the build.
Conclusion: Installing rpm via Homebrew on macOS 13 means letting Homebrew rebuild half a toolchain from source, with no control over how long it takes. This isn't a machine performance issue — it's a change in Homebrew's policy toward old macOS versions. After switching to nFPM, installation finished in a few minutes and packaging takes seconds.
Alternative: Docker + FPM
If you must use FPM's mapping syntax or already have FPM scripts, the most reliable way is to run it inside a Linux container, with macOS only responsible for compiling and mounting the directory:
bash
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o my-service ./cmd/server
chmod +x my-service
docker run --rm -v "$PWD":/src -w /src rockylinux:9 bash -c '
dnf install -y ruby rubygems rpm-build && \
gem install fpm && \
fpm -s dir -t rpm \
-n my-service -v 1.0.0 --iteration 1 \
--rpm-os linux -a x86_64 \
--description "My Go Service" \
./my-service=/usr/local/bin/my-service \
./my-service.service=/usr/lib/systemd/system/my-service.service
'Pros: doesn't pollute the macOS environment and doesn't rely on brew's rpm. Cons: requires Docker Desktop, and the first image pull takes a few minutes.
Summary
The core workflow for packaging RPMs for Go services on macOS (nFPM approach):
- Cross-compile with
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build - Prepare the systemd
.servicefile - Install nFPM with
brew install goreleaser/tap/nfpm(orgo install) - Write
nfpm.yamlto map binary and service file paths - Generate the RPM with
nfpm pkg --packager rpm --target . - Verify package contents with
rpm -qpl
Key lesson: On macOS 13, don't take the FPM route via brew install rpm — it triggers a source build of the entire toolchain with unpredictable time. Prefer the pure-Go nFPM, or fall back to packaging inside a Docker container.
Coming Next: A Real-World Project Guide
This article only covers the "get it running" layer. I'll follow up with real-world project practices and actionable tips covering:
- Directory structure and build-script conventions in real projects (one-command packaging via Makefile / shell)
- Where version numbers come from (Git tags / commit info) and how they feed into nFPM variables
- Batch multi-architecture (amd64 / arm64) builds and artifact naming conventions
- Pre/post-install hook scripts (creating users, creating directories, migrating configs, graceful restarts)
- How this ties into CI/CD pipelines, artifact repositories, and canary releases
Stay tuned — a link will be added to the end of this post once it's published.