# Building Cross-Platform System Services in Go: A Step-by-Step Guide

![Go Service](https://cdn-images-1.medium.com/max/1600/1*MUJHUBb0J0KPyq13zzY6TQ.png align="left")

### 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](https://go.dev/tour) .

#### Project Overview

```go
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:

```bash
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`

```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

```go
type Service struct {
 logFile string
 stop    chan struct{}
 wg      sync.WaitGroup
 started bool
 mu      sync.Mutex
}
```

#### Service Creation

```go
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:

```go
// 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

```go
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

```go
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`

```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`

```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`

```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`

```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:

```bash
GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o go-service.exe ./cmd/service
```

For Linux:

```bash
GOOS=linux GOARCH=amd64 go build -ldflags "-s -w" -o go-service ./cmd/service
```

For macOS:

```bash
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.
    

```bash
./go-service --install
```

* **Check the Status**: To check if the service is running, use:
    

```bash
./go-service --status
```

* **Uninstall the Service**: If you need to remove the service, use the `--uninstall` flag:
    

```bash
./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:

```bash
task --version
```

If not present, install using:

macOS

```bash
brew install go-task/tap/go-task
```

Linux

```bash
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d
```

Windows

```bash
# Using Scoop
scoop install task

# Using Chocolatey
choco install go-task
```

#### Task Configuration

Create a Taskfile.yml in your project root:

```yaml
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):

```bash
sudo task install       # Install service
task status             # Check status
sudo task uninstall     # Remove service
```

Build for your platform:

```bash
task build
```

Cross-platform builds:

```bash
task windows   # Windows build
task linux     # Linux build
task darwin    # macOS build
```

List all available tasks:

```bash
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](https://github.com/ansxuman/go-service) repository on GitHub.