zoa

  zoa is a simple, opinionated, shell-based config management tool.

  zoa is made for individuals or small teams, and works best when it comes to
  managing simple, traditional linux environments.

  it's also for individuals who are allergic to meaningless change and
  deprecation.

-> you might like zoa if:

    - you like configuration management
    - you like small & simple things
    - you run alpine, gentoo, linux from scratch, etc
    - you use a tiling window manager
    - you like messing with dotfiles
    - you dislike chef, ansible, saltstack, and puppet intensely
    - you feel like nix is overcomplicated

    you might not like zoa if:
    - you are an abstraction enjoyer
    - you dislike shell, the language
    - you dislike working in the terminal



-> quickstart (for x64 linux)

  # install zoa
     $ wget https://trash.j3s.sh/zoa
     $ chmod +x zoa
     $ mv zoa /usr/local/bin/
  # set up a zoa script
     $ printf "%s" "echo hello, world!" > hi
     $ printf "%s" "ls /noexisty" >> hi
     $ printf "%s" "uname -a" >> hi
  # execute zoa!
     $ zoa run hi

  you will notice a few interesting things:
    - zoa gently asked you to make echo posix compliant
    - zoa notified you that ls exited unsuccessfully
    - zoa printed all stdout in plaintext



-> why?

  i am a config management professional. (6+ years)
  i have worked with chef, ansible, and puppet.

  i made zoa because i think all of those config management systems are
  overcomplicated for most people / orgs.

  they're hard to keep up with, and require constant care & maintenance.

  i designed zoa for myself, and anyone like me!

  zoa uses shell - the love language of *nix systems - it won't go out of style
  :)

  zoa teaches you how to write proper posix-compatible shell, which is a
  timeless skill.

  also, shell is just fun & i love it. :D



-> design

  * 1 way
    zoa exposes only 1 hostname var, 1 copy function,
    has 0 flags, has 1 way to execute, and 1 way to 
    format your repository. less overhead for you.
  * be a turtle
    zoa is starting with a minimal set of built-in functions
    because i only want to maintain functions in order to address
    severe pain-points. most things should just be handled via plain shell.
  * as standards-compliant as reasonable
    certain standards may be flexible if the UX improvements are worth it.



-> moar info pls

  # zoa has three components
     1: the utility
     2: env vars and helpers
     3: the layout

-> 1: the utility

  zoa is a statically compiled binary, and it has no OS dependencies - simply
  download it and execute it.

  zoa expects to run as root.

  to run zoa:
    zoa run your-zoa-script
              ^
          the zoa script to execute

  that's it, you've run zoa!

-> 2: env vars and helper functions

  zoa sets some useful things up for you!

 -> env vars

  before zoa runs, it sets a few standard environment variables for your usage.

  the values shown are the defaults on my dev system.

  $PATH - search path
    PATH=/usr/local/bin:/usr/local/bin:/bin:/bin:/usr/bin:/usr/bin

  $ARCH - hardware type of the running system
    ARCH=x86_64

  $NODENAME - name of this node
    NODENAME=nostromo.j3s.sh
    * this env var may vary by distro
    * for example, it may print "nostromo" on some systems

  $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 - release level of operating system
    RELEASE=5.19.5-arch1-1
    * typically, this is the kernel version
  
  !WARNING!
    ALL $OS_RELEASE_* VARIABLES ARE NON-STANDARD, CHECK FOR THEIR EXISTENCE BEFORE
    RELYING ON THEM.

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

  $OS_RELEASE_VERSION_ID - version of your distro
    OS_RELEASE_VERSION_ID=  # arch has no version ID
    * see above warning

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



 -> helper commands

  zoa has some helper commands for common operations.

  note that you _can_ use these functions _outside_ of shell scripts, by simply
  running them.

  > zoa cp <source> <destination> [mode]
    copy a file from source to destination.

    optionally, define the permissions of the destination file (defaults to
    0644)

    zoa cp will do nothing if the files are already the same.

    examples:
      zoa cp files/sudoers /etc/sudoers
      zoa cp files/sshd_config /etc/ssh/sshd_config 0644

    TODO: dir support

  > zoa get <http/https> <destination>
    download a given url to a given destination. this is useful when the
    operating system you're running on doesn't provide wget or curl. also,
    zoa's formatting is nicer.

    examples:
      zoa get https://trash.j3s.sh/serial-experiments-lain.mp4 /home/j3s/Videos

    TODO: git support?

  > zoa watch <file> <command>...
    watch a file for changes. if any changes are detected, execute the given
    command.

    this is very useful for reloading services when their configuration files
    change.

    examples:
      $ zoa watch /etc/ssh/sshd_config systemctl restart sshd

TODO: zoa fmt



-> organization ideas

  here's how a zoa project might be organized:

         main      <-- the script you call
         files/    <-- dir containing arbitrary text files

  main is your entrypoint. you could just stick everything in main and
  be done with it, if you want.

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

  files/ contains any files that you might be interested in placing on hosts.
  "zoa cp" 



-> flexible example

  if you want zoa to be a little more capable, here's a decent starting point:

main:
  case $NODENAME 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
          export TLS_CERTS='git.j3s.sh'
          zoa run scripts/certs
          zoa run scripts/git
      ;;
      j3s.sh)
          export TLS_CERTS='j3s.sh'
          zoa run scripts/certs
          zoa run scripts/web
      ;;
  esac
scripts/certs:
  certbot renew "$TLS_CERTS"
scripts/web:
  apt install nginx
  systemctl enable --start nginx

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

### define a reusable function
in zoa, this is easy - just define a shell
function:
die() {
  printf "%s.\n" "$1"
  exit 1
}

every sub-script that is called will automatically
have access to it.

### 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, set permissions, 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