?????????????????
                ?  what is zoa  ?
                ?????????????????

  zoa is the best config management tool. it's the
  best because it's the simplest. it's written in shell, has
  a few nice little VERY USEFUL helpers, and doesn't go out
  of its way to make you hate yourself.

  zoa requires access to a git repo, though it may be used
  in local development mode.

  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 with
  minimal effort.

  it's also for individuals who like understanding their systems,
  and hate maintaining them when things break for no reason.



              why did you write this?

       i manage systems with config management tools for a living.
     i know how impossible they all are firsthand, i have 6+ years
  of painful, painful experience. i wrote zoa to use on my personal
systems, because i hate the primary config management tools a lot. 

               also, i <3 shell :D



             ~~ zoa doesn't pretend ~~

    chef & ansible & puppet & salt all pretend to be
    fully idempotent & declarative, but leave
    actual declarative-ness and idempotence as
    an exercise to the user.

      zoa doesn't pretend. zoa is not idempotent. zoa
      is not declarative. it assumes your state changes
      over time, and zoa makes it easy to keep up with those
      changes. you won't have to look at horrible doc websites
      or commit a week to learning a god
                                       damned
                                        stupid
                                          DSL

    other config management systems make their users
    feel stupid.

      zoa doesn't. zoa uses shell scripts like every
      single linux distro has used for millenia. it
      has exactly zero dependencies besides zoa itself.

      zoa adheres to standards, and uses well-known
      distro conventions.

      zoa is easy. and simple. and honestly,
      quite a smol guy

    the other tools want to do a lot - search across
    your nodes, deploy via their tooling, automate
    testing, manage AWS resources?!?!?  

      zoa is only concerned with _managing configuration_

      _on servers_

      and nothing else. forever.

    the other tools break constantly because they
    try to do everything.

      zoa breaks rarely because it does almost nothing.



               !!!!!!!!!!!!!!!!!!
               !   QUICKSTART   !
               !!!!!!!!!!!!!!!!!!

  - ~ - understand: there are three components - ~ -

          everything you need to know:

                1: the utility
                2: env vars and helpers
                3: the layout

         --- 1: the utility ---

  simply run the "zoa" tool on all of your systems. it's a simple binary (XXX: or
  shell script?) that can be installed trivially. it expects to run as root, and
  it should run on a cron/timer/whatever schedule at whatever interval you want.

  install:
    wget -O  https://j3s.sh/zoa/zoa # TODO
    mv zoa /usr/local/sbin
    chmod +x /usr/local/sbin/zoa

  design guideline: all configuration data comes from a git repository.
                             the nodes themselves keep no state at all.

  to run zoa:
    zoa https://git.j3s.sh/j3s/config main
    ^              ^                   ^
  zoa, duh.       git repo             git ref (branch or tag)

  zoa will clone the repo+ref specified (or attempt to
  fetch it, if it's already cloned) to /var/lib/zoa/repo

  zoa will then execute /var/lib/zoa/repo/main


  zoa will see that it's a different repo & will set everything up for you.

  if you run "zoa" with 0 arguments, zoa will cd to /var/lib/zoa/repo, git fetch,
  and execute the main script.

  dev mode: if you run "zoa .", zoa will execute whatever is in the $PWD - this
  is mainly for my own sanity.

  if you ever want to change the repo you're pointed at, simply run the long form
  of zoa again:

  zoa https://git.j3s.sh/j3s/a-different-zoa-repo dev

  that's it, you've configured your server! now set up a cronjob/systemd timer to
  run zoa on a schedule, if that's your thing. or just login and run zoa
  periodically.

         👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀
  you could even have the first zoa run set up a cronjob that runs zoa
  on a schedule, to make your life even easier.
         👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀


         --- 2: environment variables and helper functions ---

  in zoa, you write plain POSIX shell. Why?
  - posix shell is productive
  - posix shell is portable
  - posix shell is hard to make too complicated

                        ENVIRONMENT VARIABLES

  before zoa runs, it sets a few standard environment variables for your usage.
  here are _all of them_.

    displayed values are from my dev system
    caveats are marked with *

    $PATH - the search path for binaries. this is hardcoded.
      PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin

    $ARCH - the name of the hardware type on which the system is running
      ARCH=x86_64

    $HOSTNAME - the name of this node.
      HOSTNAME=nostromo.j3s.sh
        * there is no shortname vs fqdn standard, so this env var may vary
          by distro

    $OS - the operating system name
      OS=Linux
        * on BSD systems, this var is a lot more useful
        * if you want your distro, take a look at OS_RELEASE_ID

    $RELEASE - the current release level of the operating system implementation
      RELEASE=5.19.5-arch1-1
  
       ! WARNING: ALL $OS_RELEASE_* VARIABLES ARE UNRELIABLE !
            be sure to check for their existence before
            using them. ty~ :3

    $OS_RELEASE_ID - short uncapitalized name of your distro
      OS_RELEASE_ID=arch
        * see above warning

    $OS_RELEASE_VERSION_ID - version of your distro, if applicable
      OS_RELEASE_VERSION_ID=  # note that arch has no version ID
        * see above warning

    TODO: expose hardware info, cpu cores, ip address, memory availability, etc


                          HELPER FUNCTIONS

     zoa has some little helper functions for common operations.

      zoa-file
        usage:
          zoa-file example.conf /etc/example.conf optional-command
                    ^                ^                  ^
                  source         destination      executed if the file changes

        description:
          zoa-file takes a file from $zoa_root/files/ and places it on-disk
          somewhere. if the file is changed, a command is optionally executed.
          this can be very useful for things like reloading configurations.
      
          when you think about zoa-file, just think of it as regular cp, with an
          extra argument for running arbitrary code if the cp does anything.

        examples:
          zoa-file motd /etc/motd
          zoa-file nginx/j3s.sh /etc/nginx/conf.d/j3s.sh systemctl reload nginx

        todo:
          add a template processing step of some kind?

      zoa-script
        usage:
          zoa-script scriptname
                         ^
                   script to execute 

        description:
          zoa-script executes the given script from /var/lib/zoa/scripts/
          this is basically shorthand for ". /var/lib/zoa/repo/script/scriptname",
          and also adds some nice decorators.

        examples:
          zoa-script nginx
          zoa-script 420/69


         --- 3: the layout ---

  ah. finally. how do i lay out my zoa repo?

  here's the canonical repo layout:

         main     <-- file, entrypoint
         files/   <-- dir, contains arbitrary text files you'd like to place
         scripts/ <-- dir, contains arbitrary shell scripts to config your systems

  you need at least main! everything else is optional.

  main is your entrypoint. if your whole vibe is just doing basic configuration
  of nodes, you _could_ put literally everything in main and just be done with it.

  however, if you want main to be a little more complex,
  here's a good starting point:

      case $HOSTNAME in
          git.j3s.sh)
              # note that the CERTS env var will
              # pass into any scripts called after
              # it is defined, as if they're all 1
              # long script
              CERTS='git.j3s.sh'
              zoa-script certs
              zoa-script git
          ;;
          j3s.sh)
              CERTS='j3s.sh'
              zoa-script certs
              zoa-script web
          ;;
      esac

  scripts/ contains arbitrary shell scripts. you can organize them
  how you'd like. dirs are supported.

  files/ contains text files (no big files or binaries) that you might be
  interested in placing on hosts. these can be accessed with the zoa-file function.


               wat is borked?
      - branch cloning doesn't work rn idk why
      - the cloned git repo has root perms & git hates that
      - the repo is re-cloned on every run *shrug*


                  BONUS SECTION! :3 :3 <3 :3
          common config management patterns in zoa

### install a package

(this is distro dependent)
apt update
apt install -y cowsay

### install a package, but only if the distro is debian

if [ "$OS_RELEASE_ID" = "debian" ]; then
  apt install -y cowsay
fi
  
### place sshd_config, and reload ssh when it changes

zoa-file sshd /etc/ssh/sshd_config systemctl restart sshd
chown root:root /etc/ssh/sshd_config
chmod 0644 /etc/ssh/sshd_config

### append an iptables rule to the input chain

rule='INPUT --protocol tcp --dport 69 --jump ACCEPT'
iptables --check $rule || iptables --append $rule

### clone a remote git repo, pull it constantly

git clone git@git.sr.ht:~example/example /opt/repo ||
  git fetch /opt/repo