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 ## What a typical systemd .service file looks like
  68
  69 ```txt
  70 [Unit]
  71 Description=example-service
  72 After=network-online.target
  73 Wants=network-online.target systemd-networkd-wait-online.service
  74
  75 [Service]
  76 Restart=always
  77 StartLimitInterval=10
  78 StartLimitBurst=3
  79
  80 User=root
  81 Group=root
  82
  83 WorkingDirectory=/srv/example-service
  84 ExecStart=/srv/example-service/bin/example-command start
  85 ExecReload=/bin/kill -USR1 $MAINPID
  86
  87 # Allow the program to bind on privileged ports, such as 80 and 443
  88 CapabilityBoundingSet=CAP_NET_BIND_SERVICE
  89 AmbientCapabilities=CAP_NET_BIND_SERVICE
  90 NoNewPrivileges=true
  91
  92 [Install]
  93 WantedBy=multi-user.target
  94 ```
  95
  96 ## What a typical launchd .plist file looks like
  97
  98 ```txt
  99 <?xml version="1.0" encoding="UTF-8"?>
 100 <!-- Generated for serviceman. Edit as you wish, but leave this line. -->
 101 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 102 <plist version="1.0">
 103 <dict>
 104   <key>Label</key>
 105   <string>example-service</string>
 106   <key>ProgramArguments</key>
 107   <array>
 108     <string>/Users/me/example-service/bin/example-command</string>
 109     <string>start</string>
 110   </array>
 111
 112   <key>RunAtLoad</key>
 113   <true/>
 114   <key>KeepAlive</key>
 115   <true/>
 116
 117   <key>WorkingDirectory</key>
 118   <string>/Users/me/example-service</string>
 119
 120   <key>StandardErrorPath</key>
 121   <string>/Users/me/.local/share/example-service/var/log/example-service.log</string>
 122   <key>StandardOutPath</key>
 123   <string>/Users/me/.local/share/example-service/var/log/example-service.log</string>
 124 </dict>
 125 </plist>
 126 ```
 127
 128 ### Use `--dryrun` to see the generated launcher config:
 129
 130 ```bash
 131 sudo env PATH="$PATH" \
 132     serviceman add --system --dryrun \
 133     bash ./backup.sh /mnt/data
 134 ```
 135
 136 ### See the (sub)command help
 137
 138 The main help, showing all subcommands:
 139
 140 ```bash
 141 serviceman --help
 142 ```
 143
 144 Sub-command specific help:
 145
 146 ```bash
 147 serviceman add --help
 148 ```