Building Cross-Platform System Services in Go: A Step-by-Step Guide
A Detailed Guide to Developing Cross-Platform System Services in Go
What Are System Services?
System Services are lightweight programs that operate in the background without a graphical user interface . They start automatically during system boot and run independently.Their lifecycle, which includes operations like start, stop, and restart are managed by Service Control Manager on Windows, systemd on Linux(in most of the destro) and launchd on macOS.
Unlike standard applications, services are designed for continuous operation and are essential for tasks such as monitoring, logging, and other background processes. On linux, these services are generally referred to as daemons, while on macOS, they known as Launch Agents or Daemons.
Why Go for Building System Services**?**
Creating cross-platform system services demands a language that balances efficiency, usability, and reliability. Go excels in this regard for several reasons:
Concurrency and Performance: Go’s goroutines make it easy to run multiple tasks at once, improving efficiency and speed on different platforms. Coupled with a robust standard library, this minimizes external dependencies and enhances cross-platform compatibility.
Memory Management and Stability: Go’s garbage collection prevents memory leaks, keeping systems stable. Its clear error handling also makes it easier to debug complex services.
Simplicity and Maintainability: Go’s clear syntax simplifies writing and maintaining services . Its capability to produce statically linked binaries results in single executable files that include all necessary dependencies, eliminating the need for separate runtime environments.
Cross-Compilation and Flexibility: Go’s support for cross-compilation allows building executables for various operating systems from a single codebase. With CGO, Go can interact with low-level system APIs, such as Win32 and Objective-C, providing developers the flexibility to leverage native features.
Writing Services in Go
This code walk through assumes that GO is installed on your machine and you have a basic knowledge on GO’s syntax, if not i would highly recommend you to Take A Tour .
Project Overview
go-service/
├── Makefile # Build and installation automation
├── cmd/
│ └── service/
│ └── main.go # Main entry point with CLI flags and command handling
├── internal/
│ ├── service/
│ │ └── service.go # Core service implementation
│ └── platform/ # Platform-specific implementations
│ ├── config.go # Configuration constants
│ ├── service.go # Cross-platform service interface
│ ├── windows.go # Windows-specific service management
│ ├── linux.go # Linux-specific systemd service management
│ └── darwin.go # macOS-specific launchd service management
└── go.mod # Go module definition
Step 1: Define Configurations
Initialize the Go module:
go mod init go-service
Define configuration constants in config.go
within the internal/platform
directory. This file centralizes all configurable values, making it easy to adjust settings.
File: internal/platform/config.go
package platform
import (
"fmt"
"io"
"os"
"path/filepath"
"runtime"
)
// Update these constants with your own service configuration details.
// Replace the service name, display name, and description as needed.
// LogFileName is optional and is used to demonstrate an example service core logic
// that appends text to a file periodically.
const (
ServiceName = "go-service"
ServiceDisplay = "Go Service"
ServiceDesc = "A service that appends 'Hello World' to a file every 5 minutes."
LogFileName = "go-service-log.txt"
)
func GetInstallDir() string {
switch runtime.GOOS {
case "darwin":
return "/usr/local/opt/go-service"
case "linux":
return "/opt/go-service"
case "windows":
return filepath.Join(os.Getenv("ProgramData"), ServiceName)
default:
return ""
}
}
func copyFile(src, dst string) error {
source, err := os.Open(src)
if err != nil {
return fmt.Errorf("failed to open source file: %w", err)
}
defer source.Close()
destination, err := os.OpenFile(dst, os.O_RDWR|os.O_CREATE|os.O_TRUNC, 0755)
if err != nil {
return fmt.Errorf("failed to create destination file: %w", err)
}
defer destination.Close()
_, err = io.Copy(destination, source)
return err
}
Key features:
Service Constants which will be used during Platform-Specific Service Configurations.
GetInstallDir() provides appropriate service installation and log file paths for each OS.
copyFile() used during service installation to copy the executable to our specific path provided by GetInstallDir().
Step 2: Defining Core Service Logic
In the internal/service
, implement the core functionality for your service.The core service implementation handles the main functionality of our service.
In this example, the service appends "Hello World" to a file in the user's home directory every 5 minutes.
File: internal/service/service.go
Service Structure
type Service struct {
logFile string
stop chan struct{}
wg sync.WaitGroup
started bool
mu sync.Mutex
}
Service Creation
func New() (*Service, error) {
installDir := platform.GetInstallDir()
if installDir == "" {
return nil, fmt.Errorf("unsupported operating system: %s", runtime.GOOS)
}
logFile := filepath.Join(installDir, "logs", platform.LogFileName)
return &Service{
logFile: logFile,
stop: make(chan struct{}),
}, nil
}
Service Lifecycle
The service implements Start and Stop methods for lifecycle management:
// Start the service
func (s *Service) Start(ctx context.Context) error {
s.mu.Lock()
if s.started {
s.mu.Unlock()
return fmt.Errorf("service already started")
}
s.started = true
s.mu.Unlock()
if err := os.MkdirAll(filepath.Dir(s.logFile), 0755); err != nil {
return fmt.Errorf("failed to create log directory: %w", err)
}
s.wg.Add(1)
go s.run(ctx)
return nil
}
// Stop the service gracefully
func (s *Service) Stop() error {
s.mu.Lock()
if !s.started {
s.mu.Unlock()
return fmt.Errorf("service not started")
}
s.mu.Unlock()
close(s.stop)
s.wg.Wait()
s.mu.Lock()
s.started = false
s.mu.Unlock()
return nil
}
Main Service Loop
func (s *Service) run(ctx context.Context) {
defer s.wg.Done()
log.Printf("Service started, logging to: %s\n", s.logFile)
ticker := time.NewTicker(5 * time.Minute)
defer ticker.Stop()
if err := s.writeLog(); err != nil {
log.Printf("Error writing initial log: %v\n", err)
}
for {
select {
case <-ctx.Done():
log.Println("Service stopping due to context cancellation")
return
case <-s.stop:
log.Println("Service stopping due to stop signal")
return
case <-ticker.C:
if err := s.writeLog(); err != nil {
log.Printf("Error writing log: %v\n", err)
}
}
}
}
The run method handles the core service logic:
Key features:
Interval-based execution using ticker
Context cancellation support
Graceful shutdown handling
Error logging
Log Writing
The service appends “Hello World” with a timestamp every 5 minutes
func (s *Service) writeLog() error {
f, err := os.OpenFile(s.logFile, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
if err != nil {
return fmt.Errorf("failed to open log file: %w", err)
}
defer f.Close()
_, err = f.WriteString(fmt.Sprintf("[%s] Hello World\n", time.Now().Format(time.RFC3339)))
if err != nil {
return fmt.Errorf("failed to write to log file: %w", err)
}
return nil
}
Step 3: Creating Platform-Specific Service Configurations
The internal/platform
directory contains platform-specific configurations to install, uninstall, and manage the service.
macOS (darwin.go)
In darwin.go
, define macOS-specific logic for creating a .plist
file, which handles service installation and uninstallation using launchctl
.
File:internal/platform/darwin.go
package platform
import (
"fmt"
"os"
"os/exec"
"path/filepath"
)
type darwinService struct{}
const plistTemplate = `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>%s</string>
<key>ProgramArguments</key>
<array>
<string>%s</string>
<string>-run</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>WorkingDirectory</key>
<string>%s</string>
</dict>
</plist>`
func (s *darwinService) Install(execPath string) error {
installDir := GetInstallDir()
if err := os.MkdirAll(installDir, 0755); err != nil {
return fmt.Errorf("failed to create installation directory: %w", err)
}
// Copy binary to installation directory
installedBinary := filepath.Join(installDir, "bin", filepath.Base(execPath))
if err := os.MkdirAll(filepath.Dir(installedBinary), 0755); err != nil {
return fmt.Errorf("failed to create bin directory: %w", err)
}
if err := copyFile(execPath, installedBinary); err != nil {
return fmt.Errorf("failed to copy binary: %w", err)
}
plistPath := filepath.Join("/Library/LaunchDaemons", ServiceName+".plist")
content := fmt.Sprintf(plistTemplate, ServiceName, installedBinary, installDir)
if err := os.WriteFile(plistPath, []byte(content), 0644); err != nil {
return fmt.Errorf("failed to write plist file: %w", err)
}
if err := exec.Command("launchctl", "load", plistPath).Run(); err != nil {
return fmt.Errorf("failed to load service: %w", err)
}
return nil
}
func (s *darwinService) Uninstall() error {
plistPath := filepath.Join("/Library/LaunchDaemons", ServiceName+".plist")
if err := exec.Command("launchctl", "unload", plistPath).Run(); err != nil {
return fmt.Errorf("failed to unload service: %w", err)
}
if err := os.Remove(plistPath); err != nil {
return fmt.Errorf("failed to remove plist file: %w", err)
}
return nil
}
func (s *darwinService) Status() (bool, error) {
err := exec.Command("launchctl", "list", ServiceName).Run()
return err == nil, nil
}
func (s *darwinService) Start() error {
if err := exec.Command("launchctl", "start", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to start service: %w", err)
}
return nil
}
func (s *darwinService) Stop() error {
if err := exec.Command("launchctl", "stop", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to stop service: %w", err)
}
return nil
}
Linux (linux.go)
On Linux, we use systemd
to manage the service. Define a .service
file and related methods.
File:internal/platform/linux.go
package platform
import (
"fmt"
"os"
"os/exec"
"path/filepath"
)
type linuxService struct{}
const systemdServiceTemplate = `[Unit]
Description=%s
[Service]
ExecStart=%s -run
Restart=always
User=root
WorkingDirectory=%s
[Install]
WantedBy=multi-user.target
`
func (s *linuxService) Install(execPath string) error {
installDir := GetInstallDir()
if err := os.MkdirAll(installDir, 0755); err != nil {
return fmt.Errorf("failed to create installation directory: %w", err)
}
installedBinary := filepath.Join(installDir, "bin", filepath.Base(execPath))
if err := os.MkdirAll(filepath.Dir(installedBinary), 0755); err != nil {
return fmt.Errorf("failed to create bin directory: %w", err)
}
if err := copyFile(execPath, installedBinary); err != nil {
return fmt.Errorf("failed to copy binary: %w", err)
}
servicePath := filepath.Join("/etc/systemd/system", ServiceName+".service")
content := fmt.Sprintf(systemdServiceTemplate, ServiceDesc, installedBinary, installDir)
if err := os.WriteFile(servicePath, []byte(content), 0644); err != nil {
return fmt.Errorf("failed to write service file: %w", err)
}
commands := [][]string{
{"systemctl", "daemon-reload"},
{"systemctl", "enable", ServiceName},
{"systemctl", "start", ServiceName},
}
for _, args := range commands {
if err := exec.Command(args[0], args[1:]...).Run(); err != nil {
return fmt.Errorf("failed to execute %s: %w", args[0], err)
}
}
return nil
}
func (s *linuxService) Uninstall() error {
_ = exec.Command("systemctl", "stop", ServiceName).Run()
_ = exec.Command("systemctl", "disable", ServiceName).Run()
servicePath := filepath.Join("/etc/systemd/system", ServiceName+".service")
if err := os.Remove(servicePath); err != nil {
return fmt.Errorf("failed to remove service file: %w", err)
}
return nil
}
func (s *linuxService) Status() (bool, error) {
output, err := exec.Command("systemctl", "is-active", ServiceName).Output()
if err != nil {
return false, nil
}
return string(output) == "active\n", nil
}
func (s *linuxService) Start() error {
if err := exec.Command("systemctl", "start", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to start service: %w", err)
}
return nil
}
func (s *linuxService) Stop() error {
if err := exec.Command("systemctl", "stop", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to stop service: %w", err)
}
return nil
}
Windows (windows.go)
For Windows, use the sc
command to install and uninstall the service.
File:internal/platform/windows.go
package platform
import (
"fmt"
"os"
"os/exec"
"path/filepath"
"strings"
)
type windowsService struct{}
func (s *windowsService) Install(execPath string) error {
installDir := GetInstallDir()
if err := os.MkdirAll(installDir, 0755); err != nil {
return fmt.Errorf("failed to create installation directory: %w", err)
}
installedBinary := filepath.Join(installDir, "bin", filepath.Base(execPath))
if err := os.MkdirAll(filepath.Dir(installedBinary), 0755); err != nil {
return fmt.Errorf("failed to create bin directory: %w", err)
}
if err := copyFile(execPath, installedBinary); err != nil {
return fmt.Errorf("failed to copy binary: %w", err)
}
cmd := exec.Command("sc", "create", ServiceName,
"binPath=", fmt.Sprintf("\"%s\" -run", installedBinary),
"DisplayName=", ServiceDisplay,
"start=", "auto",
"obj=", "LocalSystem")
if err := cmd.Run(); err != nil {
return fmt.Errorf("failed to create service: %w", err)
}
descCmd := exec.Command("sc", "description", ServiceName, ServiceDesc)
if err := descCmd.Run(); err != nil {
return fmt.Errorf("failed to set service description: %w", err)
}
if err := exec.Command("sc", "start", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to start service: %w", err)
}
return nil
}
func (s *windowsService) Uninstall() error {
_ = exec.Command("sc", "stop", ServiceName).Run()
if err := exec.Command("sc", "delete", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to delete service: %w", err)
}
// Clean up installation directory
installDir := GetInstallDir()
if err := os.RemoveAll(installDir); err != nil {
return fmt.Errorf("failed to remove installation directory: %w", err)
}
return nil
}
func (s *windowsService) Status() (bool, error) {
output, err := exec.Command("sc", "query", ServiceName).Output()
if err != nil {
return false, nil
}
return strings.Contains(string(output), "RUNNING"), nil
}
func (s *windowsService) Start() error {
if err := exec.Command("sc", "start", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to start service: %w", err)
}
return nil
}
func (s *windowsService) Stop() error {
if err := exec.Command("sc", "stop", ServiceName).Run(); err != nil {
return fmt.Errorf("failed to stop service: %w", err)
}
return nil
}
Step 4: Main File Setup (main.go)
Finally, configure main.go
in cmd/service/main.go
to handle installation, uninstallation, and starting the service.
File:cmd/service/main.go
package main
import (
"context"
"flag"
"fmt"
"log"
"os"
"os/signal"
"syscall"
"time"
"go-service/internal/platform"
"go-service/internal/service"
)
func main() {
log.SetFlags(log.LstdFlags | log.Lmicroseconds)
install := flag.Bool("install", false, "Install the service")
uninstall := flag.Bool("uninstall", false, "Uninstall the service")
status := flag.Bool("status", false, "Check service status")
start := flag.Bool("start", false, "Start the service")
stop := flag.Bool("stop", false, "Stop the service")
runWorker := flag.Bool("run", false, "Run the service worker")
flag.Parse()
if err := handleCommand(*install, *uninstall, *status, *start, *stop, *runWorker); err != nil {
log.Fatal(err)
}
}
func handleCommand(install, uninstall, status, start, stop, runWorker bool) error {
platformSvc, err := platform.NewService()
if err != nil {
return err
}
execPath, err := os.Executable()
if err != nil {
return fmt.Errorf("failed to get executable path: %w", err)
}
switch {
case install:
return platformSvc.Install(execPath)
case uninstall:
return platformSvc.Uninstall()
case status:
running, err := platformSvc.Status()
if err != nil {
return err
}
fmt.Printf("Service is %s\n", map[bool]string{true: "running", false: "stopped"}[running])
return nil
case start:
return platformSvc.Start()
case stop:
return platformSvc.Stop()
case runWorker:
return runService()
default:
return fmt.Errorf("no command specified")
}
}
func runService() error {
svc, err := service.New()
if err != nil {
return fmt.Errorf("failed to create service: %w", err)
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
log.Println("Starting service...")
if err := svc.Start(ctx); err != nil {
return fmt.Errorf("failed to start service: %w", err)
}
log.Println("Service started, waiting for shutdown signal...")
<-sigChan
log.Println("Shutdown signal received, stopping service...")
if err := svc.Stop(); err != nil {
return fmt.Errorf("failed to stop service: %w", err)
}
log.Println("Service stopped successfully")
return nil
}
Building and Managing Your Service
To build your service for different operating systems, use the GOOS
and GOARCH
environment variables. For example, to build for Windows:
GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o go-service.exe ./cmd/service
For Linux:
GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o go-service ./cmd/service
For macOS:
GOOS=darwin GOARCH=amd64 go build -ldflags "-s -w" -o go-service ./cmd/service
Managing Your Service
Once you have built your service for the respective operating system, you can manage it using the following commands.
Note: Ensure to execute the commands with root privileges, as these actions require elevated permissions on all platforms.
- Install the Service: Use the
--install
flag to install the service.
./go-service --install
- Check the Status: To check if the service is running, use:
./go-service --status
- Uninstall the Service: If you need to remove the service, use the
--uninstall
flag:
./go-service --uninstall
Building and Managing Your Service using TaskFile (Optional)
Although you can use Go commands and flags to build and manage the service, I highly recommend using TaskFile. It automates these processes and provides:
Consistent commands across all platforms
Simple YAML-based configuration
Built-in dependency management
Setting Up Task
First, check if Task is installed:
task --version
If not present, install using:
macOS
brew install go-task/tap/go-task
Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d
Windows
# Using Scoop
scoop install task
# Using Chocolatey
choco install go-task
Task Configuration
Create a Taskfile.yml in your project root:
version: '3'
vars:
BINARY_NAME: go-service
BUILD_DIR: build
tasks:
build:
desc: Build the service binary for current platform
cmds:
- mkdir -p {{.BUILD_DIR}}
- go build -v -ldflags "-s -w" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} ./cmd/service
build:windows:
desc: Build for Windows
cmds:
- mkdir -p {{.BUILD_DIR}}
- GOOS=windows GOARCH=amd64 go build -v -ldflags "-s -w" -o {{.BUILD_DIR}}/{{.BINARY_NAME}}.exe ./cmd/service
build:linux:
desc: Build for Linux
cmds:
- mkdir -p {{.BUILD_DIR}}
- GOOS=linux GOARCH=amd64 go build -v -ldflags "-s -w" -o {{.BUILD_DIR}}/{{.BINARY_NAME}} ./cmd/service
build:darwin-amd64:
desc: Build for macOS (Intel)
cmds:
- mkdir -p {{.BUILD_DIR}}
- GOOS=darwin GOARCH=amd64 go build -v -ldflags "-s -w" -o {{.BUILD_DIR}}/{{.BINARY_NAME}}-amd64 ./cmd/service
build:darwin-arm64:
desc: Build for macOS (Apple Silicon)
cmds:
- mkdir -p {{.BUILD_DIR}}
- GOOS=darwin GOARCH=arm64 go build -v -ldflags "-s -w" -o {{.BUILD_DIR}}/{{.BINARY_NAME}}-arm64 ./cmd/service
build:darwin:
desc: Build for macOS (Universal Binary)
cmds:
- task: build:darwin-amd64
- task: build:darwin-arm64
- mkdir -p {{.BUILD_DIR}}
- lipo -create -output {{.BUILD_DIR}}/{{.BINARY_NAME}} {{.BUILD_DIR}}/{{.BINARY_NAME}}-amd64 {{.BUILD_DIR}}/{{.BINARY_NAME}}-arm64
- rm {{.BUILD_DIR}}/{{.BINARY_NAME}}-amd64 {{.BUILD_DIR}}/{{.BINARY_NAME}}-arm64
build:all:
desc: Build for all platforms
cmds:
- task: build:windows
- task: build:linux
- task: build:darwin
install:
desc: Install the service
deps: [build]
cmds:
- sudo ./{{.BUILD_DIR}}/{{.BINARY_NAME}} -install
uninstall:
desc: Uninstall the service
cmds:
- sudo ./{{.BUILD_DIR}}/{{.BINARY_NAME}} -uninstall
start:
desc: Start the service
cmds:
- sudo ./{{.BUILD_DIR}}/{{.BINARY_NAME}} -start
stop:
desc: Stop the service
cmds:
- sudo ./{{.BUILD_DIR}}/{{.BINARY_NAME}} -stop
status:
desc: Check service status
cmds:
- ./{{.BUILD_DIR}}/{{.BINARY_NAME}} -status
clean:
desc: Clean build artifacts
cmds:
- rm -rf {{.BUILD_DIR}}
default:
desc: Show available tasks
cmds:
- task --list
Using Task Commands
Service management (requires root/administrator privileges):
sudo task install # Install service
task status # Check status
sudo task uninstall # Remove service
Build for your platform:
task build
Cross-platform builds:
task windows # Windows build
task linux # Linux build
task darwin # macOS build
List all available tasks:
task --list
Conclusion
By following this structured approach, you can create a clean and modular service in Go that works seamlessly across multiple platforms. Each platform’s specifics are isolated in their respective files, and the main.go
file remains straightforward and easy to maintain.
For the complete code, please refer to my Go service repository on GitHub.