serviceman/README.md

   1 ---
   2 title: Serviceman
   3 homepage: https://git.rootprojects.org/root/serviceman
   4 tagline: |
   5   Serviceman: cross-platform service management for Linux, Mac, and Windows.
   6 description: |
   7   Serviceman is a hassle-free wrapper around your system launcher. It works with the default system launcher to make it easy to start _user_- and _system_-level services, such as webservers, backup scripts, network and system tools, etc.
   8
   9   Supports
  10     - `launchctl` (macOS)
  11     - `systemctl` (Linux)
  12     - The Registry (Windows)
  13 ---
  14
  15 Serviceman can run an app in just about any programming language very simply.
  16
  17 If you'd like to learn what `serviceman` does without actually making changes,
  18 add the `--dryrun` option.
  19
  20 ### Node.js
  21
  22 **Development Server**
  23
  24 ```bash
  25 pushd ./my-node-app/
  26
  27 sudo env PATH="$PATH" \
  28     serviceman add --system --cap-net-bind npx nodemon
  29 ```
  30
  31 **Production Server**
  32
  33 ```bash
  34 pushd ./my-node-app/
  35
  36 sudo env PATH="$PATH" \
  37     serviceman add --system --cap-net-bind npm start
  38 ```
  39
  40 ### Golang
  41
  42 ```bash
  43 pushd ./my-go-package/
  44
  45 sudo env PATH="$PATH" \
  46     serviceman add --system \
  47     go run -mod=vendor cmd/my-service/*.go --port 3000
  48 ```
  49
  50 ```bash
  51 pushd ./my-go-package/
  52 go build -mod=vendor cmd/my-service
  53
  54 sudo env PATH="$PATH" \
  55     serviceman add --cap-net-bind --system \
  56     ./my-service --port 80
  57 ```
  58
  59 ### And even bash!
  60
  61 ```bash
  62 sudo env PATH="$PATH" serviceman add bash ./backup.sh /mnt/data
  63 ```
  64
  65 ## What a typical systemd .service file looks like
  66
  67 ```txt
  68 [Unit]
  69 Description=example-service
  70 After=network-online.target
  71 Wants=network-online.target systemd-networkd-wait-online.service
  72
  73 [Service]
  74 Restart=always
  75 StartLimitInterval=10
  76 StartLimitBurst=3
  77
  78 User=root
  79 Group=root
  80
  81 WorkingDirectory=/srv/example-service
  82 ExecStart=/srv/example-service/bin/example-command start
  83 ExecReload=/bin/kill -USR1 $MAINPID
  84
  85 # Allow the program to bind on privileged ports, such as 80 and 443
  86 CapabilityBoundingSet=CAP_NET_BIND_SERVICE
  87 AmbientCapabilities=CAP_NET_BIND_SERVICE
  88 NoNewPrivileges=true
  89
  90 [Install]
  91 WantedBy=multi-user.target
  92 ```
  93
  94 ## What a typical launchd .plist file looks like
  95
  96 ```txt
  97 <?xml version="1.0" encoding="UTF-8"?>
  98 <!-- Generated for serviceman. Edit as you wish, but leave this line. -->
  99 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 100 <plist version="1.0">
 101 <dict>
 102   <key>Label</key>
 103   <string>example-service</string>
 104   <key>ProgramArguments</key>
 105   <array>
 106     <string>/Users/me/example-service/bin/example-command</string>
 107     <string>start</string>
 108   </array>
 109
 110   <key>RunAtLoad</key>
 111   <true/>
 112   <key>KeepAlive</key>
 113   <true/>
 114
 115   <key>WorkingDirectory</key>
 116   <string>/Users/me/example-service</string>
 117
 118   <key>StandardErrorPath</key>
 119   <string>/Users/me/.local/share/example-service/var/log/example-service.log</string>
 120   <key>StandardOutPath</key>
 121   <string>/Users/me/.local/share/example-service/var/log/example-service.log</string>
 122 </dict>
 123 </plist>
 124 ```
 125
 126 ### Use `--dryrun` to see the generated launcher config:
 127
 128 ```bash
 129 sudo env PATH="$PATH" \
 130     serviceman add --system --dryrun \
 131     bash ./backup.sh /mnt/data
 132 ```
 133
 134 ### See the (sub)command help
 135
 136 The main help, showing all subcommands:
 137
 138 ```bash
 139 serviceman --help
 140 ```
 141
 142 Sub-command specific help:
 143
 144 ```bash
 145 serviceman add --help
 146 ```