Md5sums are necessary to ensure quality of a software release. But during development it can be combersome.

A tool is available in slapos repository to update automatically md5sums for files you need to track: update-hash

In order to use this tool a dedicated file must be created containing all path and md5sum of our templates: 'buildout.hash.cfg'. software.cfg will extend this file.

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

You can access the Theia using the url and logging in with username and password.

Open index.html.in and copy this content into it:

# To learn more about how to generate this file read 
# ../../README.update-hash.rst
# THIS IS NOT A BUILDOUT FILE, despite purposedly using a compatible syntax.
# The only allowed lines here are (regexes):
# - "^#" comments, copied verbatim
# - "^[" section beginings, copied verbatim
# - lines containing an "=" sign which must fit in the following categorie.
#   - "^\s*filename\s*=\s*path\s*$" where "path" is relative to this file
#     Copied verbatim.
#   - "^\s*hashtype\s*=.*" where "hashtype" is one of the values supported
#     by the re-generation script.
#     Re-generated.
# - other lines are copied verbatim
# Substitution (${...:...}), extension ([buildout] extends = ...) and
# section inheritance (< = ...) are NOT supported (but you should really
# not need these here).

[template-cfg]
filename = instance.cfg.in
md5sum =

[instance_html5as]
_update_hash_filename_ = instance_html5as.cfg.in
md5sum =

[template_nginx_conf]
_update_hash_filename_ = templates/nginx_conf.in
md5sum =

[template_launcher]
_update_hash_filename_ = templates/launcher.in
md5sum =

[template_mime_types]
_update_hash_filename_ = templates/mime_types.in
md5sum =

[template_index_html]
_update_hash_filename_ = templates/index.html.in
md5sum =

The sections names must match the ones in software.cfg. This way by extending this file, the sections key values in software.cfg will default to the value present here.

No need to put the md5sum, they will be calculated automatically by update-hash

By extending buildout.hash.cfg, the keys in software.cfg for the sections of the same name will default to the one present in buildout.hash.cfg.

If buildout.hash.cfg has the following sections:

[template_mime_types]
_update_hash_filename_ = templates/mime_types.in
md5sum = 4ef94a7b458d885cd79ba0b930a5727e

[template_index_html]
_update_hash_filename_ = templates/index.html.in
md5sum = d57cb01df5941e139b02a2f7bdabcdc8

And software.cfg is like this:

[buildout]
extends =
  buildout.hash.cfg

[download-base]
recipe = slapos.recipe.build:download
url = ${:_profile_base_location_}/${:_update_hash_filename_}
mode = 0644

[template_mime_types_different_name]
<= download-base

[template_index_html]
<= download-base

This is equivalent to having this software.cfg:

[buildout]
# nothing extended here but listing details as following:
[template_index_html]
recipe = slapos.recipe.build:download
url = ${:_profile_base_location_}/${:_update_hash_filename_}
mode = 0644
_update_hash_filename_ = templates/index.html.in
md5sum = d57cb01df5941e139b02a2f7bdabcdc8

[template_mime_types_different_name]
recipe = slapos.recipe.build:download
url = ${:_profile_base_location_}/${:_update_hash_filename_}
mode = 0644

[template_mime_types]
_update_hash_filename_ = templates/mime_types.in
md5sum = 4ef94a7b458d885cd79ba0b930a5727e

Thanks to extend and macros, download sections are now empty in software.cfg

[instance_html5as]
# This section inherit from download-base
<= download-base
# Filename and md5sum is defined in buildout.hash.cfg

[template_nginx_conf]
<= download-base

[template_launcher]
<= download-base

[template_mime_types]
<= download-base

[template_index_html]
<= download-base

In order to update hash, running update-hash is the only thing that needs to be done.

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

1. Add a small comment in instance.cfg.in. There will be an error in the log of slapos node software due to md5sum mismatch

2. Run update-hash. It will successfully compile the software.

Try to add a comment in instance.cfg.in:

# Test for update-hash

The software will be compiled by auto-running,  you can retrieve the log of slapos node software: 

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

The error message is expected because the md5sum in buildout.hash.cfg hasn't up-to-date:

2021-03-09 18:11:05 slapos[22262] INFO While:
2021-03-09 18:11:05 slapos[22262] INFO   Installing template-cfg.
2021-03-09 18:11:05 slapos[22262] INFO Error: MD5 checksum mismatch for local resource at '/srv/slapgrid/slappart73/srv/project/slapos/software/html5as-base/instance.cfg.in'.
2021-03-09 18:11:05 slapos[22262] ERROR Failed to run buildout profile in directory '/srv/slapgrid/slappart73/srv/runner/software/ec62cb5df4d0eec6737604695dd24330'

Let's update md5sum by calling update-hash:

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

The md5sum of [template-cfg] in buildout.hash.cfg will update.

The software will be compiled by auto-running,  you can retrieve the log of slapos node software: 

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