SlapOS Home SlapOS

    How To Add A Service

    How to add a service
    • Last Update:2023-08-21
    • Version:004
    • Language:en

    Agenda

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

    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.

    Add Services

    • Services are ran 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.

    Add graceful.in

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

    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

    [template_graceful]
    _update_hash_filename_ = templates/graceful.in
    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

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

    Edit instance.cfg.in

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

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

    Render Graceful in instance_html5as.cfg.in

    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

    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 instance_html5as.cfg.in.

    [buildout]
    parts =
        ...
        nginx-graceful
    

    Add new parameter: port

    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
      }
    

    Use parameter port

    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'] }}
    ...

    Update md5sum

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

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

    Validation

    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. Make sure to edit it in your request file instead of the example one :

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

    For example,

    slapos request $software_name'_1' $software_release_uri --parameters \
    title='John Doe' \
    download_url='https://lab.nexedi.com/nexedi/converse.js/-/archive/nexedi-v4.2.0/converse.js-nexedi-v4.2.0.tar.gz' \
    port=8086

    Request:

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

    You are supposed to re-compiling and re-instantiating: 

    $ slapos node software --all
    $ slapos node instance --all

    slapos node software (--all) and slapos node instance (--all)are the commands for compiling and instantiating. Before instantiating please make sure that the compilation is completed.
    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.

    Note : you have to remove slapos supply $software_release_uri slaprunner from the request script ! (Either by deleting or using #). Look below for an example. 

    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 server_url(using new port)

    The same output is expected.