A README

@@ -0,0 +1,87 @@ 
+                ?????????????????
+                ?  what is dis  ?
+                ?????????????????
+
+  zoa is the best config management tool ever. it's the
+  best because it's just written in posix shell & provides
+  a few nice little VERY USEFUL helpers, but doesn't go out
+  of its way to make you hate yourself.
+  
+  it's also very opinionated about layout - there's generally
+  1 correct way to do most common things.
+  
+  zoa is intended for human-scale deployment, and generally
+  works best if you're not trying to manage a crazy complicated
+  fleet of systems between multiple teams. zoa is for small,
+  tight-knit teams who want to keep it all in their heads.
+
+               !!!!!!!!!!!!!!!!!!
+               !   QUICKSTART   !
+               !!!!!!!!!!!!!!!!!!
+
+  - ~ - understand: there are three components - ~ -
+
+  1: the utility
+  2: the language
+  3: the layout
+
+         --- 1: the utility ---
+
+  simply run the daemon on all of your systems. it's a simple binary (XXX: or
+  shell script?) that can be installed trivially. it wants to run as root, and
+  it should run on a cron schedule at whatever interval you want.
+
+  install:
+    wget -O  https://j3s.sh/zoa
+    mv zoa /usr/local/sbin
+    chmod +x /usr/local/sbin/zoa
+
+  in order to run zoa, you name a repo and a branch:
+    zoa https://git.cyberia.club/cyberia/layerze.ro.git main
+
+  zoa will clone the repo+branch specified in your config (or attempt to
+  fetch it, if it's already cloned) to /var/lib/zoa/<repo>/<branch>
+
+  when zoa runs, it sets a few env vars for your usage:
+    DISTRO="$(cat /etc/os-release | grep ^ID | cut -d = -f 2-)"
+
+  then it simply executes.
+
+  that's it, you've configured your server! set up a cronjob/systemd timer to
+  run zoa on a schedule, if that's your thing. or just login and run it
+  periodically. you could even have the first run set up a cronjob that runs it
+  👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀
+
+         --- 2: the language ---
+
+  basically, you can write plain shell, and there are some helpers for 90% of
+  what configuration management is about.
+
+  helpers:
+    # install package
+    pkg 'htop'
+    # place file
+    
+    # set permissions
+
+         --- 3: the layout ---
+
+  ah finally, how do i lay out my git repo? here's the canonical doc:
+
+  files/
+  funcs/
+  hosts/
+
+  you need at least hosts/ - everything else is optional
+  hosts/ contains shell scripts that run on the host(s) specified - for example,
+  if i run zoa from domechild.cyberia.club, and this file is present:
+
+  hosts/domechild.cyberia.club
+
+  then that is my entrypoint.
+
+  funcs/ contains defs that are automatically available across all of your hosts &
+  files.
+
+  files/ contains text files (no big files or binaries pls) that you might be
+  interested in placing on hosts.

A hosts/host.example.org

@@ -0,0 +1,92 @@ 
+# install a file, set permissions, and update
+# the apk repos if things have changed
+#
+# note that ZOA_FILES is available for use!
+# $ZOA_FILES is equal to /var/lib/zoa/<repo>/<branch>/files/
+mkdir -p /etc/apk
+cp "$ZOA_FILES/repositories" /etc/apk/repositories
+chown root:root /etc/apk/repositories
+chmod 0644 /etc/apk/repositories
+apk update
+
+# this is pretty typical - the above works just fine.
+# however, zoa provides a useful helper to wrap the
+# above into a single line:
+#   remember: file, owners, perms
+#   and optionally: a command to run if the file is updated
+
+zoa-file repositories /etc/apk/repositories root:root 0644 'apk update'
+
+# zoa-file will only run "apk update" if the file is changed, or if its permissions
+# change. zoa-file also gives you more pretty output.
+
+# install useful packages (this is idempotent already!)
+apk add ip6tables nano vim htop tmux tree curl wget prometheus-node-exporter@edge-community pigz
+
+# install another file
+# note that this time, we don't run a command!
+zoa-file motd /etc/motd root:root 0644
+
+# zoa keeps track of all file changes throughout the run (done via zoa-file)
+# so you can always reference them
+
+zoa-changed /etc/motd
+# exits 0 now since the file was modified this run :D
+
+# setup cron & metrics
+apk add chrony
+zoa-file prom_collect /usr/bin/prom-collect root:root 0755
+zoa-file cyberia-alpine-metrics /etc/periodic/daily/cyberia-alpine-metrics
+
+# and now, a directory...
+mkdir -p /var/lib/prometheus/textfile_collector
+chown root:root /var/lib/prometheus/textfile_collector
+chmod 0777 /var/lib/prometheus/textfile_collector
+
+# of course, there's a shortcut:
+zoa-directory /var/lib/prometheus/textfile_collector root:root 0777
+
+# and of course, the shortcut gives us the ability to run a command & prints
+# slightly prettier output when zoa runs.
+
+# and naturally, dirs show up in zoa-changed as well
+zoa-changed /var/lib/prometheus/textfile_collector
+# exits 0
+
+zoa-file node-exporter /etc/conf.d/node-exporter root:root 0644
+
+# just handle service management via shell
+# per usual, bust out a little for loop even
+for service in chronyd crond syslog klogd node-exporter; do
+  service $service start
+  rc-update add $service
+done
+
+# if you want to do something more OS-specific:
+
+if [ "$DISTRO" = "debian" ]; then
+  # these init commands are idempotent as well
+  # since they'll just do nothing and exit cleanly
+  # if the service is already started/enabled
+  systemctl start docker
+  systemctl enable docker
+fi
+
+# ???what have we learned so far???
+# files and dirs - zoa wraps that & provides helpers
+# services and package management - DIY
+
+zoa-file cyberian_authorized_ssh_keys /home/cyberian/.ssh/authorized_keys cyberian:cyberian 0600
+
+# here we can see the use of our first "var" - all of the vars in the /vars
+# dir are automatically applied to the nodes within the files.
+for operator in $operators; do
+  # adduser is not in zoa because there's no POSIX standard
+  # thus it would be very costly to capture all possible OS permutations
+  # and the author of zoa values his time
+  #
+  # besides, it's pretty easy to automate:
+  adduser -D "$operator" || true
+  zoa-directory "/home/$operator/.ssh" "$operator:$operator" 0700
+  zoa-file "ssh_keys/$operator" "/home/$operator/.ssh/authorized_keys" cyberian:cyberian 0600
+done