Updated Tutorial: Creating a (micro) service (asciidoc)

Tutorial:-Creating-a-(micro)-service.asciidoc

@@ -36,6 +36,8 @@ onSignal(SIGABRT):
 # Add handlers for SIGSTOP, SIGQUIT as needed
 
 let conf = parseFile(config_file_name)
+# Traditional logging to file. To use the more featureful journald you might
+# use https://github.com/FedericoCeratto/nim-morelogging
 let fl = newFileLogger(conf["log_fname"].str, fmtStr = "$datetime $levelname ")
 fl.addHandler
 
@@ -54,7 +56,7 @@ when isMainModule:
 
 === Example templates
 
-Create /var/lib/myservicename/temaplates/base.tmpl
+Simple HTML templates. Create /var/lib/myservicename/temaplates/base.tmpl
 [source,nim]
 ----
 #? stdtmpl | standard
@@ -98,6 +100,7 @@ Create /lib/systemd/system/myservicename.service file. Configure CapabilityBound
 ----
 [Unit]
 Description=myservicename
+# Optional documentation hints
 Documentation=man:myservicename
 Documentation=https://github.com/REPLACEME/myservicename
 After=network.target httpd.service squid.service nfs-server.service mysqld.service named.service postfix.service
@@ -106,8 +109,11 @@ Wants=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=/var/lib/myservicedir/
+# stdbuf buffers the stdout in order not to block your application
 ExecStart=/usr/bin/stdbuf -oL /var/lib/myservicedir/myservicename
+# wait 10s when stopping
 TimeoutStopSec=10
+# SIGTERM the master process and later on SIGKILL any stray process
 KillMode=mixed
 KillSignal=SIGTERM
 
@@ -120,13 +126,17 @@ LimitNOFILE=65536
 
 # Hardening
 NoNewPrivileges=yes
+# Set process capabilities. Fine-tune as needed.
 CapabilityBoundingSet=CAP_DAC_READ_SEARCH
+# Create private /dev /tmp /home to isolate the process
 PrivateDevices=yes
 PrivateTmp=yes
 ProtectHome=yes
 ProtectSystem=full
+# Log any stdout/stderr to syslog/journald
 StandardOutput=syslog+console
 StandardError=syslog+console
+# Allow RW access to some dirs. Add yours as needed.
 ReadWriteDirectories=/proc/self
 ReadWriteDirectories=-/var/run
 
@@ -134,6 +144,7 @@ ReadWriteDirectories=-/var/run
 WantedBy=multi-user.target
 ----
 
+An example variable config file for your application.
 Create /var/lib/myservicedir/conf.json
 [source,json]
 ----