Use a configuration file for Canto's init script

etc/canto-docker-initd

@@ -1,23 +1,33 @@
-#! /bin/sh
+#!/bin/sh
 # /etc/init.d/canto
 
+### BEGIN INIT INFO
+# Provides:          canto
+# Required-Start:    $remote_fs $syslog
+# Required-Stop:     $remote_fs $syslog
+# Default-Start:     2 3 4 5
+# Default-Stop:      0 1 6
+# Short-Description: Canto community annotation tool
+### END INIT INFO
+
 # Installation instructions: https://github.com/pombase/canto/blob/master/etc/canto-init.d.md
 
 action=$1
-port=$2
 
+PORT=5000
 WORKERS=5
-CANTO_SPACE=/var/canto-space
-
+CANTO_SPACE=/var/canto_space
 PID_PATH=import_export/canto.pid
 
+if [ -f /etc/default/canto ]; then
+  . /etc/default/canto
+fi
+
 # Carry out specific functions when asked to by the system
 case "$action" in
   start)
-
     echo "Starting Canto with $WORKERS workers"
-
-    (date; cd $CANTO_SPACE; canto/script/canto_docker --non-interactive --use-container-name start_server --pid-file=/$PID_PATH --port $port -- script/canto_start --workers $WORKERS --keepalive-timeout 5 -s Starman --preload) >> canto.log 2>&1 &
+    (date; cd $CANTO_SPACE; canto/script/canto_docker --non-interactive --use-container-name start_server --pid-file=/$PID_PATH --port $PORT --signal-on-hup=QUIT --signal-on-term=QUIT -- script/canto_start --workers $WORKERS --keepalive-timeout 5 -s Starman) >> $CANTO_SPACE/canto.log 2>&1 &
     ;;
   stop)
     pid=`/bin/cat $CANTO_SPACE/$PID_PATH`
@@ -36,4 +46,3 @@ case "$action" in
 esac
 
 exit 0
-

etc/canto-init.d.md

@@ -1,61 +1,136 @@
-## Instructions for setting up Canto as an init.d script.
+# Instructions for running Canto as an init script
 
-This assumes you have an existing, initialised `canto-space` directory at
-`/var/canto-space`.  See the
+This assumes you have an existing, initialised `canto_space` directory (at
+`/var/canto_space` by default). See the
 [main Canto documentation](https://curation.pombase.org/docs/canto_admin/installation)
 for details.
 
-On your server you'll need to install this script somewhere:
+First, you will need the Canto init script from the Canto repository:
 
-  https://github.com/pombase/canto/blob/master/etc/canto-docker-initd
+<https://github.com/pombase/canto/blob/master/etc/canto-docker-initd>
 
-An example would be: `/sbin/canto-docker-initd`.
+Copy this script to `/etc/init.d/canto` on your server, and make it executable
+with the following command:
 
-And make it executable with:
+```sh
+chmod a+x /etc/init.d/canto
+```
+
+You may also need to change the owner of the script to the `root` user:
 
 ```sh
-  chmod a+x /sbin/canto-docker-initd
+chown root:root /etc/init.d/canto
 ```
 
-And then you'll need a create a file named `/etc/init.d/canto` with
-these contents:
+## Installing the service
+Instructions are shown below for installing Canto as a service using various
+service managers. Once installed with either system, Canto should start
+automatically whenever the machine (or virtual machine) boots.
+### update-rc.d
+
+If your server uses the `update-rc.d` command, run the following command to
+install the `canto` service:
 
-  https://github.com/pombase/canto/blob/master/etc/example-canto-docker-init.d
+```sh
+update-rc.d canto defaults
+```
 
-And make it executable with:
+Now you can start Canto with the following command:
 
 ```sh
-  chmod a+x /etc/init.d/canto
+/etc/init.d/canto start
 ```
 
-If your "canto-docker-initd" is in a different location you'll need to
-edit /etc/init.d/canto
+restart with:
 
+```sh
+/etc/init.d/canto restart
+```
 
-After those two files are in place, run:
+and stop with:
 
 ```sh
-  update-rc.d canto defaults
+/etc/init.d/canto stop
 ```
 
-Now you can start canto with:
+### systemd
+
+If your server uses `systemd`, run the following command to
+install the `canto` service:
 
 ```sh
-  /etc/init.d/canto start
+systemctl enable canto
 ```
+(The Canto init script is not a native systemd service, but systemd should
+still be able to install the script.)
 
-Restart with
+Now you can use the `service` command to manage Canto like any other systemd
+service. You can start Canto with:
 
 ```sh
-  /etc/init.d/canto restart
+service canto start
 ```
 
-And stop with
+restart with:
 
 ```sh
-  /etc/init.d/canto stop
+service canto restart
 ```
 
-For troubleshooting, a log file is written to `/var/canto-space/canto.log`.
+and stop with:
+
+```sh
+service canto stop
+```
+
+## Configuring the service
+
+The Canto repository provides a file called `canto.defaults` that can be used
+to configure parts of the service. This file is completely optional.
+
+The configuration file can be found here:
 
-Canto will now start automatically when the machine/VM reboots.
+<https://github.com/pombase/canto/blob/master/etc/canto.defaults>
+
+Copy this script to `/etc/default/canto` on your server.
+
+To configure the service, simply uncomment the line in `/etc/default/canto` 
+that has the variable you want to change, and set a value for the variable.
+For example, to change the port number to 7000, the file would be changed 
+as follows:
+
+```sh
+# Port number for Canto's web server.
+PORT=7000
+```
+
+The `canto.defaults` file allows the following variables to be configured:
+
+* `PORT`: the port number for Canto's web server. Defaults to port
+  number 5000.
+
+* `WORKERS`: the number of worker processes used by the
+  [Starman](https://metacpan.org/pod/Starman) web server. Defaults to 
+  5 workers. You may want to adjust this to suit the memory requirements
+  of your server.
+
+* `CANTO_SPACE`: the path to the base directory of the Canto application.
+  Defaults to `/var/canto_space`. Note that this is the path to the 
+  containing directory for the `canto`, `data` and `import_export`
+  directories; it is _not_ the path to the `canto` directory itself.
+
+* `PID_PATH`: the path to the process ID file for the Server::Starter process.
+  Defaults to `import_export/canto.pid`. Note that this path is relative to 
+  the root of the Docker container's filesystem, and cannot be set to any 
+  path that does not exist in both the host filesystem and the container.
+  You should not normally need to configure this value.
+
+## Logging and troubleshooting
+
+The service file writes output from Canto to a log file at
+`/var/canto_space/canto.log`. If you are using systemd, you can also use
+the following command to check the service status:
+
+```sh
+service canto status
+```

etc/canto.defaults

@@ -0,0 +1,19 @@
+# Canto service configuration file for SysVinit
+
+# Copy this file to /etc/default/canto. Set values for the variables below and 
+# uncomment them to override the default configuration in the init script. The 
+# file will be sourced by /etc/init.d/canto.
+
+# Port number for Canto's web server.
+#PORT=
+
+# Number of workers for Server::Starter.
+#WORKERS=
+
+# Directory path for Canto. Note that this is the path to the containing 
+# directory for the 'canto', 'data' and 'import_export' directories, not the 
+# path to the 'canto' directory itself.
+#CANTO_SPACE=
+
+# Path to the process ID file for the Server::Starter process.
+#PID_PATH=