new design
Jes Olson j3s@c3f.net
Tue, 22 Nov 2022 18:59:36 -0800
M
README
→
README
@@ -1,352 +1,231 @@
- ????????????????? - ? what is zoa ? - ????????????????? + + zoa zoa is a simple, opinionated, shell-based config management tool. - it's the best. it's pull-based. - zoa makes you feel good about config management. + zoa is made for individuals or small teams, and works best when it comes to + managing simple, traditional linux environments. - zoa config lives in a git repo, and all of the systems you manage - simply point at the repo. + it's also for individuals who are allergic to meaningless change and + deprecation. - 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. +-> you might like zoa if: - it's also for individuals who like understanding their systems, - and hate maintaining them when things break for no reason. + - 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 like zoa if: - - you enjoy 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 like smallness and simplicity - - you think nix just seems way too god-damned complicated + you might not like zoa if: + - you are an abstraction enjoyer + - you dislike shell, the language + - you dislike working in the terminal - you might not like zoa if: - - you are an abstraction enjoyer - - you dislike shell, the language - - you dislike the terminal in general +-> quickstart (for x64 linux) - -> quickstart (for linux) - - # install zoa - $ wget https://trash.j3s.sh/zoa - $ chmod +x zoa - $ mv zoa /usr/local/bin/ - # set up your very own zoa repo - $ mkdir zoa - $ cd zoa - $ mkdir scripts files - $ printf 'uname -a' > main - # finally, run zoa against your server - $ zoa deploy j3s.sh - - done! - - - - why did you write this? (are you insane) - - first, yes, duh, but also: - i manage systems with config management tools for a living. (6+ years) - i know how impossible they all are to operate & keep up with - years of painful, painful experience. i wrote zoa to use on my personal -systems, because i hate the main config management tools a lot. - - also, i <3 shell :D + # install zoa + $ wget https://trash.j3s.sh/zoa + $ chmod +x zoa + $ mv zoa /usr/local/bin/ + # set up a zoa script + $ printf 'hello, world!\n' > main + # execute zoa! + $ zoa run main - ~~ zoa doesn't pretend ~~ +-> why? - this section is a rant that i'll convert into a blog post tbh + i am a config management professional. (6+ years) + i have worked with chef, ansible, and puppet. - chef & ansible & puppet & salt all pretend to be - fully idempotent & declarative, but leave - actual declarative-ness and idempotence as - an exercise to the user. + i made zoa because i think all of those config management systems are + overcomplicated for most people / orgs. - 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 + they're hard to keep up with, and require constant care & maintenance. - other config management systems make their users - feel stupid. + i designed zoa for myself, and anyone like me! - 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 uses shell - the love language of *nix systems - it won't go out of style + :) - zoa adheres to standards, and uses well-known - distro conventions. + zoa teaches you how to write proper posix-compatible shell, which is a + timeless skill. - zoa is easy. and simple. and honestly, - quite a smol guy + also, shell is just fun & i love it. :D - 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_ +-> design - and nothing else. forever. + * 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. - the other tools break constantly because they - try to do everything. - zoa breaks rarely because it does almost nothing. - other tools are slow because they have HUGE runtimes and scopes +-> moar info pls - zoa is comparatively fast, because it's just running god dang - shell scripts :3 - zoa doesn't require: - - ssh - - python - - ruby - - a chef server or salt master + # zoa has three components + 1: the utility + 2: env vars and helpers + 3: the layout - other tools abstract too much +-> 1: the utility - zoa abstracts a few definitely useful functions, but - otherwise gets out of the way and gives you a light - framework to speak shell to your systems. + zoa is a statically compiled binary, and it has no OS dependencies - simply + download it and execute it. - in zoa, you write plain POSIX shell. Why? - - posix shell is productive! - - posix shell is portable! - - posix shell is the language of system configuration! - - posix shell is easy to remember! - - posix shell rarely changes! + 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! - zoa's design touchstones - ------------------------ - * no config on the nodes - node-side config is cumbersome. everything - should be adjustable via git and git alone. - * expose 1 way to do common things - zoa exposes only 1 hostname var, only 1 copy function, - has 0 flags, and 1 way to run via git, and 1 way to - format your repository. less overhead for you. - * adopt functionality slowly - 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 shell. - * as standards-compliant as reasonable +-> 2: env vars and helper functions + zoa sets some useful things up for you! + -> env vars - !!!!!!!!!!!!!!!!! - ! DETAILS ! - !!!!!!!!!!!!!!!!! + before zoa runs, it sets a few standard environment variables for your usage. - - ~ - understand: there are three components - ~ - + the values shown are the defaults on my dev system. - everything you need to know: + $PATH - search path + PATH=/usr/local/bin:/usr/local/bin:/bin:/bin:/usr/bin:/usr/bin - 1: the utility - 2: env vars and helpers - 3: the layout + $ARCH - hardware type of the running system + ARCH=x86_64 - --- 1: the utility --- + $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 - zoa is a single binary. + $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 - it expects to run as root (it is managing your system, after all), - and it should probably run on a cron/timer/whatever schedule at - whatever interval you want. - - installation process: - wget https://j3s.sh/zoa/zoa # TODO - mv zoa /usr/local/bin - chmod +x /usr/local/bin/zoa - - to run zoa: - zoa https://git.j3s.sh/j3s/config main - ^ ^ ^ - zoa, duh. git repo optional git branch - - zoa will clone the repo+branch specified to /var/lib/zoa/repo, and then - it will execute the "main" script in that repo - more on that later. - - to run zoa in local-only mode: - zoa /path/to/zoa/dir + $RELEASE - release level of operating system + RELEASE=5.19.5-arch1-1 + * typically, this is the kernel version - in which case, zoa will just execute main from that dir you specify + !WARNING! + ALL $OS_RELEASE_* VARIABLES ARE NON-STANDARD, CHECK FOR THEIR EXISTENCE BEFORE + RELYING ON THEM. - that's it, you've run zoa! 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. + $OS_RELEASE_ID - short uncapitalized name of your distro + OS_RELEASE_ID=arch + * see above warning - 👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀 - you could even have the first zoa run set up a cronjob that runs zoa - on a schedule, to make your life even easier. - 👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀👀 + $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 - --- 2: environment variables and helper functions --- - ENVIRONMENT VARIABLES - before zoa runs, it sets a few standard environment variables for your usage. - here are _all of them_. + -> helper commands - displayed values are from my dev system - caveats are marked with * + zoa has some helper commands for common operations. - $PATH - the search path for binaries. this is hardcoded. - PATH=/usr/local/bin:/usr/local/bin:/bin:/bin:/usr/bin:/usr/bin + note that you _can_ use these functions _outside_ of shell scripts, by simply + running them. - $ARCH - the name of the hardware type on which the system is running - ARCH=x86_64 + > zoa cp <source> <destination> [mode] + copy a file from source to destination. - $NODENAME - the name of this node. - NODENAME=nostromo.j3s.sh - * there is no shortname vs fqdn standard, so this env var may vary - by distro + optionally, define the permissions of the destination file (defaults to + 0644) - $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 + zoa cp will do nothing if the files are already the same. - $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 + examples: + zoa cp files/sudoers /etc/sudoers + zoa cp files/sshd_config /etc/ssh/sshd_config 0644 - $OS_RELEASE_ID - short uncapitalized name of your distro - OS_RELEASE_ID=arch - * see above warning + TODO: dir support - $OS_RELEASE_VERSION_ID - version of your distro, if applicable - OS_RELEASE_VERSION_ID= # note that arch has no version ID - * see above warning + > 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. - TODO: expose hardware info, cpu cores, ip address, memory availability, etc + examples: + zoa get https://trash.j3s.sh/serial-experiments-lain.mp4 /home/j3s/Videos + TODO: git support? - HELPER FUNCTIONS + > zoa watch <file> <command>... + watch a file for changes. if any changes are detected, execute the given + command. - zoa has some little helper functions for common operations. + this is very useful for reloading services when their configuration files + change. - * zoa-clone <git repo> - usage: - zoa-clone https://git.cyberia.club/my-zoa-repo branchname - ^ ^ - git repo to clone optional git branch + examples: + $ zoa watch /etc/ssh/sshd_config systemctl restart sshd - description: - zoa-clone will clone a given git repository to the local - system at ~/.local/share/zoa/repo - if the repository is - already cloned, zoa will fetch it. - is provided for a few reasons: - - no need to install git on your servers (zoa is git-capable) - - clone + exec is a very common zoa pattern - * 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 - +-> organization - --- 3: the layout --- + here's how a zoa project should be organized: - 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 - scripts/ <-- dir, contains arbitrary shell scripts + main <-- the main shell script + files/ <-- dir containing arbitrary text files + scripts/ <-- dir containing other shell scripts - you need at least main. everything else is optional. + you need at least main. files/ is optional. main is your entrypoint. you could just stick everything in main and be done with it, if you want. - however, if you want main to be a little more capable, - here's one starting point: - - 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 - 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. + files/ contains any files that you might be interested in placing on hosts. + "zoa cp" - wat is borked? - - custom functions don't work within if statements - - 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* +::super fun example:: + if you want zoa to be a little more capable, here's a decent starting point: + + 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 BONUS SECTION! :3 :3 <3 :3 common config management patterns in zoa@@ -360,7 +239,7 @@ exit 1
} every sub-script that is called will automatically -have access to it. env vars work the same way. +have access to it. ### install a package
A
rant.md
@@ -0,0 +1,70 @@
+ ~~ zoa doesn't pretend ~~ + + this section is a rant that i'll convert into a blog post tbh + + 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. + + other tools are slow because they have HUGE runtimes and scopes + + zoa is comparatively fast, because it's just running god dang + shell scripts :3 + zoa doesn't require: + - ssh + - python + - ruby + - a chef server or salt master + + other tools abstract too much + + zoa abstracts a few definitely useful functions, but + otherwise gets out of the way and gives you a light + framework to speak shell to your systems. + + in zoa, you write plain POSIX shell. Why? + - posix shell is productive! + - posix shell is portable! + - posix shell is the language of system configuration! + - posix shell is easy to remember! + - posix shell rarely changes! + +