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 \
  29     npx nodemon ./server.js
  30 ```
  31
  32 **Production Server**
  33
  34 ```bash
  35 pushd ./my-node-app/
  36
  37 sudo env PATH="$PATH" \
  38     serviceman add --system --cap-net-bind \
  39     npm start
  40 ```
  41
  42 ### Golang
  43
  44 ```bash
  45 pushd ./my-go-package/
  46
  47 sudo env PATH="$PATH" \
  48     serviceman add --system \
  49     go run -mod=vendor cmd/my-service/*.go --port 3000
  50 ```
  51
  52 ```bash
  53 pushd ./my-go-package/
  54 go build -mod=vendor cmd/my-service
  55
  56 sudo env PATH="$PATH" \
  57     serviceman add --cap-net-bind --system \
  58     ./my-service --port 80
  59 ```
  60
  61 ### And even bash!
  62
  63 ```bash
  64 sudo env PATH="$PATH" serviceman add bash ./backup.sh /mnt/data
  65 ```
  66
  67 ### How to see all services
  68
  69 ```bash
  70 serviceman list --system
  71 serviceman list --user
  72 ```
  73
  74 ```txt
  75 serviceman-managed services:
  76
  77         example-service
  78 ```
  79
  80 ### How to restart a service
  81
  82 You can either `add` the service again (which will update any changed options),
  83 or you can `stop` and then `start` any service by its name:
  84
  85 ```bash
  86 sudo env PATH="$PATH" serviceman stop example-service
  87 sudo env PATH="$PATH" serviceman start example-service
  88 ```
  89
  90 ## What a typical systemd .service file looks like
  91
  92 ```txt
  93 [Unit]
  94 Description=example-service
  95 After=network-online.target
  96 Wants=network-online.target systemd-networkd-wait-online.service
  97
  98 [Service]
  99 Restart=always
 100 StartLimitInterval=10
 101 StartLimitBurst=3
 102
 103 User=root
 104 Group=root
 105
 106 WorkingDirectory=/srv/example-service
 107 ExecStart=/srv/example-service/bin/example-command start
 108 ExecReload=/bin/kill -USR1 $MAINPID
 109
 110 # Allow the program to bind on privileged ports, such as 80 and 443
 111 CapabilityBoundingSet=CAP_NET_BIND_SERVICE
 112 AmbientCapabilities=CAP_NET_BIND_SERVICE
 113 NoNewPrivileges=true
 114
 115 [Install]
 116 WantedBy=multi-user.target
 117 ```
 118
 119 ## What a typical launchd .plist file looks like
 120
 121 ```txt
 122 <?xml version="1.0" encoding="UTF-8"?>
 123 <!-- Generated for serviceman. Edit as you wish, but leave this line. -->
 124 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 125 <plist version="1.0">
 126 <dict>
 127   <key>Label</key>
 128   <string>example-service</string>
 129   <key>ProgramArguments</key>
 130   <array>
 131     <string>/Users/me/example-service/bin/example-command</string>
 132     <string>start</string>
 133   </array>
 134
 135   <key>RunAtLoad</key>
 136   <true/>
 137   <key>KeepAlive</key>
 138   <true/>
 139
 140   <key>WorkingDirectory</key>
 141   <string>/Users/me/example-service</string>
 142
 143   <key>StandardErrorPath</key>
 144   <string>/Users/me/.local/share/example-service/var/log/example-service.log</string>
 145   <key>StandardOutPath</key>
 146   <string>/Users/me/.local/share/example-service/var/log/example-service.log</string>
 147 </dict>
 148 </plist>
 149 ```
 150
 151 ### Use `--dryrun` to see the generated launcher config:
 152
 153 ```bash
 154 sudo env PATH="$PATH" \
 155     serviceman add --system --dryrun \
 156     bash ./backup.sh /mnt/data
 157 ```
 158
 159 ### See the (sub)command help
 160
 161 The main help, showing all subcommands:
 162
 163 ```bash
 164 serviceman --help
 165 ```
 166
 167 Sub-command specific help:
 168
 169 ```bash
 170 serviceman add --help
 171 ```