Update documentation for canto-docker-initd

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
+```