Add A Service


  • Add Services
  • Add Graceful Template
  • Download graceful template
  • Render Graceful template
  • Verification

This Tutorial describe 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 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.

Add Services

  • Services are run by supervisord.
  • Any executable placed in INSTANCE-ROOT/etc/run/ will automatically be considered a service.
  • To add a service to an instance, render its executable in INSTANCE-ROOT/etc/run/

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/ 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'] }})

Add graceful in buildout.hash.cfg

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

_update_hash_filename_ = templates/
md5sum =

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

Download graceful in software.cfg

Update software.cfg to download the template

context =
  key template_graceful_target template_graceful:target

<= download-base


Edit to make the template available to

template_graceful  = {{ template_graceful_target }}

Render Graceful in

Add a new section [nginx-graceful] 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
recipe = slapos.recipe.template:jinja2
template = {{ parameter_list['template_graceful'] }}
rendered = ${basedirectory:script}/nginx-graceful
mode = 0700
context =
    section param_html5as html5as

Add graceful to processed parts

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

parts =

Add new parameter: port

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

port = 8081

Use parameter port

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

# Network
port = ${slap-parameter:port}

Update md5sum

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

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


  1. Request instance with port=8086
  2. Verify Exited Graceful Status
  3. Verify server_url with port=8086

To validate this tutorial, we are supposed to request the instance with port parameter and have graceful exited. 

Request instance with port=8086

Refer How To Add A Parameter to have the instance requested with port parameter:

Add port parameter in request script:

slapos request $sofware_name'_1' $software_release_uri --parameters ... port=8086


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

The instance will be re-instantiated by auto-running. You are supposed to inspect the log of slapos node instance

$ tail -fn 100  ~/srv/runner/var/log/slapos-node-instance.log

You can observe that the output of request script is still with 8081 port for server_url, which will be replaced by 8086 as you edited in the request script.

Verify Exited Graceful Status

$ slapos node status
slappart0:nginx-graceful         EXITED    Mar 11 11:42 AM

nginx-graceful is EXITED as expected.

Verify server_url with port=8086

New server_url connection parameter use port 8086. The link can be curled:

$ curl http://[2001:67c:1254:45:a9d5::dd2e]:8086

The same output is expected.

Thank You

  • Nexedi SA
  • 147 Rue du Ballon
  • 59110 La Madeleine
  • France
  • +33629024425

For more information, please contact Jean-Paul, CEO of Nexedi (+33 629 02 44 25).