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