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