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
internal/apply/apply.go
+100 -2
View File
@@ -33,6 +33,7 @@ import (
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/jmap"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state"
)
// Images are the defaults. They are tags rather than digests for now: the
@@ -185,6 +186,16 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
return nil, err
}
// A machine that already runs this installation is converged, not set up
// again. First boot happens once: bootstrap, the first administrator, the
// first account, the ACME account. Running it a second time asks a
// configured server for bootstrap credentials it stopped accepting the
// moment it was configured -- which is exactly what adding or removing a
// front end used to do, and why it could not.
if existing, err := state.Load(); err == nil && existing.Installed() {
return converge(ctx, o, stack, cmp, existing, f, log)
}
// The bootstrap credential lives in an override file for this step only,
// and its password only in this process. Bringing the stack up afterwards
// without the override recreates the server without the variable, so no
@@ -237,7 +248,11 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
log.Info("administrator %s, password in %s", admin.Username, filepath.Join(dir, "credentials.txt"))
log.Step("starting the rest of the stack")
if err := cmp.Run(ctx, "up", "-d"); err != nil {
// --remove-orphans: the compose file is rendered from the shapes asked
// for, so a component the topology no longer lists is simply not in it
// any more. Without this its container would keep running, belonging to
// a project that no longer describes it.
if err := cmp.Run(ctx, "up", "-d", "--remove-orphans"); err != nil {
return res, err
}
@@ -286,7 +301,15 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
}
}
if !o.Local {
// Certificates need something holding port 80 for the HTTP-01 challenge,
// which is the proxy. Asked for on a machine with no proxy, the order
// can only fail -- so this says whose job it is instead of leaving a
// failed ACME account behind and stopping the install over it.
if !o.Local && !stack.Proxy {
log.Info("no proxy here, so certificates are yours to arrange: the server's own names are %s",
strings.Join(stack.ServerNames(), ", "))
}
if !o.Local && stack.Proxy {
log.Step("turning on certificates")
if _, err := srv.EnableACME(ctx, domainID, o.ACMEDirectory, o.ACMEEmail); err != nil {
return res, fmt.Errorf("enabling ACME: %w", err)
@@ -319,6 +342,23 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
return res, err
}
// What this machine now runs, written down so the next run diffs against
// intent rather than guessing from what happens to be up.
st, err := state.Load()
if err == nil {
st.Machine, st.Dir, st.Domain = o.Machine, dir, o.Domain
st.Runtime, st.Topology = f.Runtime.Kind, o.TopologyPath
st.Shapes = map[string]string{}
for _, c := range []plan.Component{plan.Server, plan.Console, plan.Webmail} {
if sh := o.Shape(c); sh != plan.Skip {
st.Shapes[string(c)] = string(sh)
}
}
if err := st.Save(); err != nil {
log.Info("could not write %s: %v", state.Path, err)
}
}
zone, err := srv.DNSZone(ctx, domainID)
if err == nil && zone != "" {
res.ZoneFile = filepath.Join(dir, "dns.zone")
@@ -360,6 +400,64 @@ func waitForCertificate(ctx context.Context, srv *jmap.Client, log Log, domainID
return ""
}
// converge brings an installed machine in line with what it is now asked to
// run: the deployment is rewritten from the shapes chosen, the stack is
// brought up, and anything no longer in the file goes with --remove-orphans.
// Nothing touches the mail: data volumes are left alone, and a component
// that is removed can be added back with what it had.
func converge(ctx context.Context, o plan.Options, stack compose.Stack, cmp docker.Compose,
st *state.State, f host.Facts, log Log) (*Result, error) {
res := &Result{
Dir: o.Dir, ConsoleURL: stack.ConsoleURL, WebmailURL: stack.WebmailURL,
ServerURL: stack.ServerPublicURL,
}
if b, err := os.ReadFile(filepath.Join(o.Dir, "credentials.txt")); err == nil {
for _, line := range strings.Split(string(b), "\n") {
if fields := strings.Fields(line); len(fields) == 2 && fields[0] == "administrator" {
res.AdminUser = fields[1]
}
}
}
log.Step("bringing the stack in line with the file")
if err := cmp.Run(ctx, "up", "-d", "--remove-orphans"); err != nil {
return res, withLogs(ctx, err, cmp, "server")
}
// The server reads the front-end URLs from its environment, so a front
// end that was added or removed changes what it was started with. Only
// restart when that actually changed.
if st.Shapes["console"] != string(o.Shape(plan.Console)) || st.Shapes["webmail"] != string(o.Shape(plan.Webmail)) {
log.Info("the front ends changed, so the server is restarted to see them")
if err := cmp.Run(ctx, "restart", "server"); err != nil {
return res, err
}
// Do not report a finished converge over a server that is still
// coming back: a few seconds of refused connections is the one
// moment of this that looks like an outage, and it should be over
// before the command returns.
if err := waitFor(ctx, log, "the server to answer again", 120*time.Second, func(ctx context.Context) error {
return live(ctx, "http://"+stack.ServerBind)
}); err != nil {
return res, withLogs(ctx, err, cmp, "server")
}
}
st.Machine, st.Dir, st.Domain = o.Machine, o.Dir, o.Domain
st.Runtime, st.Topology = f.Runtime.Kind, o.TopologyPath
st.Shapes = map[string]string{}
for _, c := range []plan.Component{plan.Server, plan.Console, plan.Webmail} {
if sh := o.Shape(c); sh != plan.Skip {
st.Shapes[string(c)] = string(sh)
}
}
if err := st.Save(); err != nil {
log.Info("could not write %s: %v", state.Path, err)
}
return res, nil
}
// Verify is the last step: does what was installed actually answer?
func Verify(ctx context.Context, res *Result, stackConsole, stackWebmail bool, log Log) []string {
var problems []string