diff --git a/README.md b/README.md index e165cbf..978e454 100644 --- a/README.md +++ b/README.md @@ -5,15 +5,98 @@ Ozai just does the minimal thing you want in a process watcher/restarter: 1. Start thing. 2. Watch thing. 3. Restart thing. +4. __No external dependencies at all.__ -No random ass Hugo includes. No forced upgrades to the latest possible Go. No randomly included +No random ass Hugo includes. [No forced upgrades to the latest possible Go](https://github.com/air-verse/air/releases/tag/v1.63.0). No randomly included entire web interfaces for no reason. Just the simplest thing needed for the task and no more. - ## Getting Started +> __WARNING__ This is imaginary right now. I need to dogfood this in my own dev process and refine +> these docs. + +You can install it with the Go 1.24 `go get -tool` feature: + +```shell +go get -tool https://lcthw.dev/go/ozai +``` + +Then you edit a config file that says what to run and how to run it (see below). Once you have that +you can run it with: + +```shell +go tool ozai +``` + +And it should start all your configured processes. + ## Config File Format +The config is a simple JSON file that defines the processes to run and what reset URL to use. +Here's an example that runs two copies of the `tools/cmd/tester` test commands: + +```javascript +{ + "Processes": { + "tester1": { + "URL": "/tester1", + "Command": "tester", + "Args": ["-count", "100", "-id", "1"] + }, + "tester2": { + "URL": "/tester2", + "Command": "tester", + "Args": ["-count", "500", "-id", "2"] + } + } +} +``` + +* `"Processes"` -- All of your processes go in here. There may be other options that are meta + option which is why I did this. +* `"tester1":` -- This is an internal key used to identify it in logs. +* `"URL:"` -- The URL that you'll use to restart this process. +* `"Command:"` -- The command (binary, .exe) to run. +* `"Args:"` -- The args to pass to the command as options. __MUST BE STRINGS__ + +That's it. More may come as I use it but for now it just does what it says it does. ## Restart HTTP URLs + +Projects like Air try to be a passive build tool (and site generator, and Go promotion systems, and +Delta Wing Combat Engine, and Alien Defense System, and Cake Baking Cockroach) but ozai lets you +just use your existing build tool to tell it when to restart things. Rather than monitor all of +your files (which never goes right), you just do this: + +```shell +curl http://127.0.0.1:9999/tester1 +``` + +That's it. When Ozai receives that request it just restarts that process and keeps going. You can +then toss this into a Makefile or other build tool and every time you build it'll kick things over. +Dead simple and works 100% of the time. + +Many things about Air are then fixed with this design: + +1. Air tries to build your whole web application when you just change one .css file. +2. The auto refresh in the browser _also_ needs to have a build error notice because Air is doing your building. +3. When there's a build failure, you have to go look at Air's output rather than just using your existing IDE or editor's existing error handline. +4. When you accidentally refresh while Air is doing a build you get a huge delay in the browser, it errors out, then you have to wait and hit refresh again anyway, defeating the whole purpose of the auto-refresh feature. + +## Beta Software + +Even though this is working this is a 3 day hack because Air decided their latest release would +force me to upgrade my Go, which caused all of my projects to fail and cost me an hour of work. It +still need actual usage by me to sort out any necessary features, but for the most part it's +useable. + +Things I may add: + +* Additional configuration options like the port and base URL to use. +* Whether a process should restart or not. +* Logging process output to a file. +* _Maybe_ a little TUI that emulates some tmux stuff. Not sure. I guess just use tmux but I'm on + windows so I'd like this. + +That's it. Enjoy.