inbuxa/inbuxa-installer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Describe an installation in a file, and converge to it

Browse Source 
One file describes the whole installation: which machine runs what, under
which names. Each machine acts on its own part of it and prints the command
to run on the others, which nobody but their operator runs. Emit, never
execute -- no agent, no console-held credential, no machine reaching
another.

  inbuxa plan  -f topology.json     what would change here; changes nothing
  inbuxa apply -f topology.json     make this machine match it
  inbuxa export                     the file, from what is already here

plan diffs the file against what is installed rather than against what
happens to be running: a container stopped by hand is still installed, and
offering to install it again would be a lie about what is about to happen.
The state that makes that possible -- intent, which the machine itself
cannot tell you -- is /etc/inbuxa/install.json.

Front ends across machines, not a clustered mail server. Two machines each
running one is refused, and the refusal says why: a second node needs a
shared store and cluster configuration, which this does not set up. Two of
the same component on one machine is refused too -- two webmails need two
ports and two names, and the file says neither.

The shrink is the half worth proving, and it found the bug that mattered:
apply ran first boot every time, so the second one asked a configured server
for bootstrap credentials it had stopped accepting, and adding or removing a
front end could not work at all. An installed machine now converges instead:
the deployment is rewritten from the shapes asked for, --remove-orphans
takes away what the file no longer lists, data volumes are left alone, and
the secrets generated the first time are kept rather than rolled.

Two more found the same way:

- Certificates were turned on even where nothing holds port 80. On a machine
  with no proxy the order can only fail, and it stopped the install over it.
  It now says whose job they are instead.
- A converge that restarts the server reported "Done" while it was still
  coming back. It waits.

Twenty-eight checks, on Debian 13 and Fedora 43: install from a file, plan
the same file and be told there is nothing to do, remove the webmail and
watch it go while the mail stays, put it back.
This commit is contained in:
jcoffey-dev
2026-09-24 09:51:16 -07:00
parent b6bc126651
commit a90df656e7
9 changed files with 893 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
cmd/inbuxa/main.go
+173
View File
@@ -10,6 +10,7 @@ package main
import (
"context"
"encoding/json"
"flag"
"fmt"
"io"
@@ -22,6 +23,8 @@ import (
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/deps"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/topology"
)
// version is stamped by the release build; a build from a working tree says
@@ -33,6 +36,9 @@ const usage = `inbuxa -- install the inbuxa suite on this machine
inbuxa install [flags] install or converge (no flags: the interface)
inbuxa survey what this machine is, as the installer sees it
inbuxa deps [--install] what is missing for a shape, and fix it
inbuxa plan -f FILE what a topology file would change here
inbuxa apply -f FILE make this machine match that file
inbuxa export [-o FILE] write a topology file from what is here
inbuxa version this program's version
install flags:
@@ -89,6 +95,12 @@ func main() {
os.Exit(survey())
case "deps":
os.Exit(depsCmd(os.Args[2:]))
case "plan":
os.Exit(topologyCmd(os.Args[2:], false))
case "apply":
os.Exit(topologyCmd(os.Args[2:], true))
case "export":
os.Exit(exportCmd(os.Args[2:]))
case "version":
fmt.Println(version)
case "-h", "--help", "help":
@@ -269,6 +281,167 @@ func depsCmd(args []string) int {
return 0
}
// topologyCmd is plan and apply: the same reading of the same file, one of
// which stops after printing.
//
// A machine acts on its own part of the file and prints what the others have
// to run. It never reaches them -- the file is copied across by whoever owns
// those machines, and run there. That is the whole security posture of the
// designer this is the executor for: emit, never execute.
func topologyCmd(args []string, doIt bool) int {
fs := flag.NewFlagSet("plan", flag.ContinueOnError)
fs.Usage = func() { fmt.Print(usage) }
var (
file = fs.String("f", "", "")
machineName = fs.String("machine", "", "")
yes = fs.Bool("yes", false, "")
installDeps = fs.Bool("install-deps", false, "")
)
if err := fs.Parse(args); err != nil {
return 2
}
if *file == "" {
fmt.Fprintln(os.Stderr, "which file? pass -f topology.json")
return 2
}
t, err := topology.Load(*file)
if err != nil {
fmt.Fprintln(os.Stderr, err.Error())
return 1
}
name := *machineName
if name == "" {
h, _ := os.Hostname()
name = h
}
m, ok := t.Machine(name)
if !ok {
fmt.Fprintf(os.Stderr, "this machine is %q, which the file does not mention.\n", name)
fmt.Fprintf(os.Stderr, "It describes: %s\n", strings.Join(machineNames(t), ", "))
fmt.Fprintln(os.Stderr, "Pass --machine to say which one this is.")
return 1
}
st, err := state.Load()
if err != nil {
fmt.Fprintln(os.Stderr, err.Error())
return 1
}
d := topology.Compare(st, m)
fmt.Print(d.String())
fmt.Print(topology.Elsewhere(t, *file, name))
if !doIt {
return 0
}
if d.Empty() {
return 0
}
if !*yes {
fmt.Fprintln(os.Stderr, "\nNothing has happened yet. Pass --yes to carry this out.")
return 1
}
// Removals are the half that can lose something. Naming them again here,
// after the diff and before the work, is the last chance to read them.
if rm := d.Removals(); len(rm) > 0 {
fmt.Println()
for _, c := range rm {
fmt.Printf(" removing %s from this machine; its data volumes are left in place\n", c.Component)
}
}
o := plan.Options{
Domain: t.Domain, MailHost: t.MailHost, ConsoleHost: t.ConsoleHost,
WebmailHost: t.WebmailHost, ACMEEmail: t.ACMEEmail,
Dir: m.Dir, Proxy: m.Proxy, InstallDeps: *installDeps,
Machine: name, TopologyPath: *file,
}
for _, kind := range []plan.Component{plan.Server, plan.Console, plan.Webmail} {
sh := plan.Skip
if s := m.Shape(string(kind)); s != "" {
sh = plan.Shape(s)
}
o.Choices = append(o.Choices, plan.Choice{Component: kind, Shape: sh})
}
f := host.Survey(context.Background())
p, err := plan.Build(f, o)
if err != nil {
fmt.Fprintln(os.Stderr, "\ncannot apply this file here: "+err.Error())
return 1
}
fmt.Println("\nApplying:")
log := &printer{}
res, err := apply.Run(context.Background(), p, f, log)
if err != nil {
fmt.Fprintln(os.Stderr, "\nstopped: "+err.Error())
return 1
}
fmt.Printf("\nDone. %s\n", res.Dir)
if res.AdminUser != "" {
fmt.Printf(" administrator %s\n", res.AdminUser)
}
return 0
}
// exportCmd writes what is on this machine as a topology file, so a design
// starts from a system that exists rather than a blank page.
func exportCmd(args []string) int {
fs := flag.NewFlagSet("export", flag.ContinueOnError)
fs.Usage = func() { fmt.Print(usage) }
out := fs.String("o", "", "")
if err := fs.Parse(args); err != nil {
return 2
}
st, err := state.Load()
if err != nil {
fmt.Fprintln(os.Stderr, err.Error())
return 1
}
if !st.Installed() {
fmt.Fprintln(os.Stderr, "nothing is installed here, so there is nothing to describe")
return 1
}
name := st.Machine
if name == "" {
name, _ = os.Hostname()
}
m := topology.Machine{Name: name, Dir: st.Dir}
for _, kind := range []string{"server", "console", "webmail"} {
if sh, ok := st.Shapes[kind]; ok {
m.Components = append(m.Components, topology.Component{Kind: kind, Shape: sh})
}
}
t := &topology.Topology{Version: topology.Version, Domain: st.Domain, Machines: []topology.Machine{m}}
t.Defaults()
if err := t.Validate(); err != nil {
fmt.Fprintln(os.Stderr, "what is installed here does not describe a whole installation: "+err.Error())
fmt.Fprintln(os.Stderr, "(a machine running only front ends is one part of a file, not all of it)")
return 1
}
if *out == "" {
b, _ := json.MarshalIndent(t, "", " ")
fmt.Println(string(b))
return 0
}
if err := t.Save(*out); err != nil {
fmt.Fprintln(os.Stderr, err.Error())
return 1
}
fmt.Printf("wrote %s\n", *out)
return 0
}
func machineNames(t *topology.Topology) []string {
var out []string
for _, m := range t.Machines {
out = append(out, m.Name)
}
return out
}
func shape(s string) (plan.Shape, error) {
switch strings.ToLower(s) {
case "skip", "no", "none":