From be09ba17ae5e0cf6739793ce424b8544c585aea1 Mon Sep 17 00:00:00 2001 From: James Seager Date: Tue, 22 Jun 2021 11:37:29 +0100 Subject: [PATCH 1/7] Source canto-docker-initd configuration from canto.defaults --- etc/canto-docker-initd | 14 +++++++------- etc/canto.defaults | 17 +++++++++++++++++ 2 files changed, 24 insertions(+), 7 deletions(-) create mode 100644 etc/canto.defaults diff --git a/etc/canto-docker-initd b/etc/canto-docker-initd index 86a67625c..7062c1cf5 100755 --- a/etc/canto-docker-initd +++ b/etc/canto-docker-initd @@ -1,23 +1,24 @@ -#! /bin/sh +#!/bin/sh # /etc/init.d/canto # 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 - 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 -- script/canto_start --workers $WORKERS --keepalive-timeout 5 -s Starman --preload) >> canto.log 2>&1 & ;; stop) pid=`/bin/cat $CANTO_SPACE/$PID_PATH` @@ -36,4 +37,3 @@ case "$action" in esac exit 0 - diff --git a/etc/canto.defaults b/etc/canto.defaults new file mode 100644 index 000000000..bd0ba6360 --- /dev/null +++ b/etc/canto.defaults @@ -0,0 +1,17 @@ +# Canto service configuration file for SysVinit + +# Move 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 for Canto's source files. +#CANTO_SPACE= + +# Path to the process ID file for the Server::Starter process. +#PID_PATH= From c76eb5ca2488ea5c2a850edaabe30549566f5757 Mon Sep 17 00:00:00 2001 From: James Seager Date: Tue, 22 Jun 2021 11:40:12 +0100 Subject: [PATCH 2/7] Remove intermediary Canto init script --- etc/canto-docker-initd | 9 +++++++++ etc/example-canto-docker-init.d | 16 ---------------- 2 files changed, 9 insertions(+), 16 deletions(-) delete mode 100755 etc/example-canto-docker-init.d diff --git a/etc/canto-docker-initd b/etc/canto-docker-initd index 7062c1cf5..a4eb8d651 100755 --- a/etc/canto-docker-initd +++ b/etc/canto-docker-initd @@ -1,6 +1,15 @@ #!/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 diff --git a/etc/example-canto-docker-init.d b/etc/example-canto-docker-init.d deleted file mode 100755 index 3cd8b4904..000000000 --- a/etc/example-canto-docker-init.d +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/sh - -# -### BEGIN INIT INFO -# Provides: canto -# Required-Start: $remote_fs $syslog -# Required-Stop: $remote_fs $syslog -# Should-Start: -# Should-Stop: -# Default-Start: 2 3 4 5 -# Default-Stop: 0 1 6 -# Short-Description: Canto -### END INIT INFO -# - -su -c "/sbin/canto-docker-initd $* 7000" root & - From b037547cd69a2d8b7cf618a85b4e9d446a7b8cfc Mon Sep 17 00:00:00 2001 From: James Seager Date: Tue, 29 Jun 2021 15:17:40 +0100 Subject: [PATCH 3/7] Amend comments in canto.defaults --- etc/canto.defaults | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/etc/canto.defaults b/etc/canto.defaults index bd0ba6360..5da7f184c 100644 --- a/etc/canto.defaults +++ b/etc/canto.defaults @@ -1,6 +1,6 @@ # Canto service configuration file for SysVinit -# Move this file to /etc/default/canto. Set values for the variables below and +# 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. @@ -10,7 +10,9 @@ # Number of workers for Server::Starter. #WORKERS= -# Directory for Canto's source files. +# 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. From 5315b71e3e4f53a36415fd1cbbe64fbe51d8a13e Mon Sep 17 00:00:00 2001 From: James Seager Date: Wed, 30 Jun 2021 11:28:34 +0100 Subject: [PATCH 4/7] 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 +``` From 652a2dc8270ffa748c8da6bb170248bbddb8b37d Mon Sep 17 00:00:00 2001 From: James Seager Date: Mon, 26 Jul 2021 13:55:26 +0100 Subject: [PATCH 5/7] Replace canto-space with canto_space in init files --- etc/canto-docker-initd | 2 +- etc/canto-init.d.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/etc/canto-docker-initd b/etc/canto-docker-initd index a4eb8d651..a360a4b52 100755 --- a/etc/canto-docker-initd +++ b/etc/canto-docker-initd @@ -16,7 +16,7 @@ action=$1 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 diff --git a/etc/canto-init.d.md b/etc/canto-init.d.md index dbb701b8c..ed581c3b4 100644 --- a/etc/canto-init.d.md +++ b/etc/canto-init.d.md @@ -1,7 +1,7 @@ # Instructions for running Canto as an init script -This assumes you have an existing, initialised `canto-space` directory (at -`/var/canto-space` by default). 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. @@ -115,7 +115,7 @@ The `canto.defaults` file allows the following variables to be configured: 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 + 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. @@ -128,7 +128,7 @@ The `canto.defaults` file allows the following variables to be configured: ## 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 +`/var/canto_space/canto.log`. If you are using systemd, you can also use the following command to check the service status: ```sh From 8748bc9b367d67c4151ae54fd8cabb65d7281ecd Mon Sep 17 00:00:00 2001 From: Kim Rutherford Date: Wed, 28 Jul 2021 21:08:06 +1200 Subject: [PATCH 6/7] Fix shutdown signals for canto_start --- etc/canto-docker-initd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/etc/canto-docker-initd b/etc/canto-docker-initd index a360a4b52..9393db015 100755 --- a/etc/canto-docker-initd +++ b/etc/canto-docker-initd @@ -27,7 +27,7 @@ fi 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.log 2>&1 & ;; stop) pid=`/bin/cat $CANTO_SPACE/$PID_PATH` From c9c39ab18e7c7b44c2cea87aad07ca1f8fd8baf9 Mon Sep 17 00:00:00 2001 From: James Seager Date: Wed, 28 Jul 2021 12:10:19 +0100 Subject: [PATCH 7/7] Use absolute path for init script log file --- etc/canto-docker-initd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/etc/canto-docker-initd b/etc/canto-docker-initd index 9393db015..da2b4a3bd 100755 --- a/etc/canto-docker-initd +++ b/etc/canto-docker-initd @@ -27,7 +27,7 @@ fi 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 --signal-on-hup=QUIT --signal-on-term=QUIT -- script/canto_start --workers $WORKERS --keepalive-timeout 5 -s Starman) >> 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`