This tutorial describes how to deploy a new service running in the instance.

HTML5AS instance already has one service running, Nginx the server serving the website. Here we will add a graceful restart service to Nginx so that any change in its configuration is taken into account.

To illustrate this process in html5as we will introduce the following elements:

• A template to send the signal to Nginx for gracefully restart.
• Add a new parameter port to dynamically change the listening port for nginx.

Without the graceful service, the change of the listening port in the configuration wouldn't be taken into account until the next hard restart of nginx. This only happens when the server reboot in the case of a production environment. The graceful service will exit upon sending the signal to nginx but will be restarted automatically every time the instance is processed by slapos node making sure nginx is running with the latest configuration.

Here is the commit introducing this functionality to html5as Software release: commit diff.

Services that are not running will be started automatically at the end of an instanciation.

The process of adding a new template has already be covered in How To Add A Template

HUP Signal is sent to the process by the kill command to request a graceful restart. The pid must be obtained from the pid file used by nginx and defined in the instance profile.

Add a new template file in templates/graceful.in with the following content

#! {{ param_html5as['path_shell'] }}
# BEWARE: This file is operated by slapos node
# BEWARE: It will be overwritten automatically

# Run graceful
exec kill -s SIGHUP $(cat {{ param_html5as['path_pid'] }})

In order to track the new file and automatically update its md5sum, it needs to be added to buildout.hash.cfg

[template_graceful]
_update_hash_filename_ = templates/graceful.in
md5sum =

You can refer HowTo Update MD5 Checksum in Theia to get more information.

Update software.cfg to download the template

[template-cfg]
...
context =
....
  key template_graceful_target template_graceful:target

...
[template_graceful]
<= download-base

Edit instance.cfg.in to make the template available to instance_html5as.cfg.in

[profile-common]
...
template_graceful  = {{ template_graceful_target }}

Add a new section [nginx-graceful] in instance_html5as.cfg.in to render the template.

mode is 0700 to be an executable. The section param_html5as is passed as context to get the pid file of nginx.

### Nginx Graceful
[nginx-graceful]
recipe = slapos.recipe.template:jinja2
template = {{ parameter_list['template_graceful'] }}
rendered = ${basedirectory:script}/nginx-graceful
context =
    section param_html5as html5as

The new graceful section won't be processed because no other section depend on it. This is why nginx-graceful must be added to the list of parts to be processed by buildout in instance_html5as.cfg.in.

[buildout]
parts =
    ...
    nginx-graceful

Add a new parameter port in [slap-parameter] section of instance_html5as.cfg.in. For backward compatibility the port default to 8081 

default-parameters =
  {
    "title": "Tutorial html5as",
    "download_url": "",
    "port": 8081
  }

Update the configuration of the port key in the [html5as] section of instance_html5as.cfg.in by using ${slap-parameter:port} instead of hard-coded 8081

[html5as]
...
# Network
...
port = {{ parameter_dict['port'] }}
...

Refer How To Move to md5sum automatic update to update md5sum:

$ cd ~/srv/project/slapos/software/html5as-base
$ ../../update-hash