From 5315b71e3e4f53a36415fd1cbbe64fbe51d8a13e Mon Sep 17 00:00:00 2001 From: James Seager Date: Wed, 30 Jun 2021 11:28:34 +0100 Subject: [PATCH] Update documentation for canto-docker-initd --- etc/canto-init.d.md | 125 +++++++++++++++++++++++++++++++++++--------- 1 file changed, 100 insertions(+), 25 deletions(-) diff --git a/etc/canto-init.d.md b/etc/canto-init.d.md index 3f69ce14e..dbb701b8c 100644 --- a/etc/canto-init.d.md +++ b/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 + -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. + + +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 +```