system updates

this repo contains system updates applied to nodes in incremental form as text/source code. a node periodically runs the update.sh script, which pulls the repo and executes apply.sh to apply any new changes to the system.

updates are implemented as shell scripts that perform incremental changes to the system (e.g. upgrading services, adjusting configuration, applying system fixes). all changes are expected to be idempotent and safe to run on already updated systems.

typical update examples are: upgrade bitcoind, lnd and other services, system packages, improve configuration of components such as firewall. the run sequence on the node is approximately as follows:

1. fetch updates with a git fetch.
2. provide a git diff on the screen and confirm with the user.
3. pull in the changes with a git pull --verify-signatures.
4. run apply.sh.

at the moment, an on-screen diff and confirmation aren't implemented yet. nd and ngui is where it'll happen, in the ndg repo.

when configuring a new node, clone this repo and set up a cron job to execute the update.sh script once a day. The script requires REPODIR and LOGFILE env variables set.

TODO: add a list of supported platforms; the "native" is void linux.

release channels

this repository uses two long-lived branches to represent update channels:

• master – stable / production channel (stable in UI)
• dev – development channel (edge in UI)

by default, nodes should track master, which is considered stable and safe for production use.

promoting changes from dev to master

when a change is merged to dev, it should be tested on a physical device for at least a few days before being merged to master.

git checkout master
git merge -S dev
git push

testing a live change

the procedure to run a modified sysupdate on the device while ssh'ed into the instance.

first, make sure periodic updates are disabled:

chmod -x /etc/cron.hourly/sysupdate

then set required env variables and run the apply script:

cd /ssd/sysupdates
export SYSUPDATES_ROOTDIR=$PWD
./apply.sh

to reactivate periodic sysupdates, flip the x bit:

chmod +x /etc/cron.hourly/sysupdate

note that the periodic sysupdate script will revert the repo to the latest commit of the branch specified in the script or master as the default.

contributing

fork the repo, make changes in a feature branch and submit a pull request. feature branch must be based off the latest dev.

all commits must be signed using gpg with signature added to your github account. to sign a commit, use:

git commit -S -m "commit message"

all changes must be tested on a physical device before merging to dev.

our branch protection rules also require linear history, so use rebase instead of merge when updating your feature branch with latest dev changes. before merging a PR, make sure to rebase on latest dev and resolve any conflicts.

unless it really makes sense to do otherwise, all changes must be incremental, i.e., do not bundle multiple unrelated changes in a single PR. each PR should ideally address a single concern only.

see squashing commits on how to combine multiple commits into one.