Skip to content

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

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 ​

ApproachDependenciesExperience on macOS 13Recommendation
nFPMPure-Go binary, no rpmbuildFast install, no source build⭐⭐⭐⭐⭐ Top pick
FPM + brew rpmRuby + rpmbuild toolchainTriggers massive source builds, unpredictable time⭐⭐ Backup
Docker + FPMDocker DesktopClean 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-service

Note: Keeping CGO_ENABLED=0 produces 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.target

Step 3: Install nFPM ​

The recommended way is GoReleaser's tap, which provides the latest version:

bash
brew install goreleaser/tap/nfpm

If you don't mind a slightly older version, you can also use the Homebrew core repository version (faster to install):

bash
brew install nfpm

Verify the installation:

bash
nfpm --version

Alternative: If brew installation also hits bottle issues, you can install directly with Go — it only compiles nFPM itself, with very few dependencies:

bash
go 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.yaml

Create 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: 0644

Key points:

  • mode: 0755 ensures the binary has execute permission (nFPM won't add the executable bit automatically)
  • platform: linux and arch: amd64 must match GOOS/GOARCH; for ARM targets, change to arch: arm64
  • version and release together form the RPM version number 1.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.rpm

You 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):

  1. Cross-compile with CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build
  2. Prepare the systemd .service file
  3. Install nFPM with brew install goreleaser/tap/nfpm (or go install)
  4. Write nfpm.yaml to map binary and service file paths
  5. Generate the RPM with nfpm pkg --packager rpm --target .
  6. 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.

Last updated on11/17/2026, 12:22 PM
@fishfinal | @fishfinals | [email protected]