Files
inbuxa-installer/internal/plan/plan.go
T
jcoffey-dev c9245077fa Phase 2: the console and the webmail on the host
--console host and --webmail host install them without containers, from
their releases' tarballs (inbuxa-admin #106, inbuxa-webmail #68), each
checked against a checksum pinned in internal/release.

- The console is files: unpacked into <dir>/console, root-owned and
  readable, and pointed at the server the way its image's entrypoint does
  (the api-base-url meta tag). The managed Caddy serves the directory,
  mounted read-only, or the operator's web server does from the
  configuration --proxy snippets writes; both with the image's rules (app
  routes fall back to index.html, hashed assets cached for good, index.html
  never). With --local or --proxy none nothing would serve it, and the
  plan says so.
- The webmail is the /app its image runs, in <dir>/webmail, owned by root,
  under inbuxa-webmail.service as its own user on the installer's own Node
  (now 26, as its image) in /opt/inbuxa/node, on 127.0.0.1:8080, with the
  container's environment in <dir>/webmail.env. It can't write its own
  files, which is what its IMMUTABLE setting checks. The unit is
  ProtectSystem=strict. A server in a container is reached at its loopback
  port and sees it at the project network's gateway, which is what gets
  exempted from the auto-ban.
- Both unpack beside the old copy and swap only when complete; a re-run
  skips an unchanged release and restarts the webmail only when what it
  reads at start changed. A webmail moved back into a container gives its
  port back first. status and export report them as host.

With all three on the host and --proxy snippets, no container runtime is
installed. The release pins are empty until those releases exist, and the
host shapes say so; INBUXA_CONSOLE_TARBALL and INBUXA_WEBMAIL_TARBALL (and
CONSOLE_TARBALL=, WEBMAIL_TARBALL= in e2e/vm/run.sh) install a local
tarball meanwhile.

Also: the "using docker" line no longer prints when nothing runs in a
container; Verify takes the plan's options and checks a host console by
its files.

Tests: plan (console host needs a web server; host front ends wait for
their releases; the webmail wants the installer's own Node), compose
(console files, the webmail unit, Caddy on the host's network, the
gateway exemption, nginx serving the directory), apply (api-base-url
replaced or inserted, the webmail's environment, unpack's swap and
marker). e2e: webmail-host.sh 18/18 (signing in included), all-host.sh
17/17 (no runtime, behind nginx), both with tarballs taken out of the
current images as the release jobs will; install-local, install-host,
install-public, proxy-snippets, interface, status-export and topology
pass unchanged.
2026-10-12 11:26:03 -07:00

584 lines
19 KiB
Go

// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
// Package plan turns what the operator chose, and what the machine is, into
// the list of things that would happen -- before any of them do.
//
// Everything the installer does goes through a plan. The interface shows it
// on its fifth screen, `--dry-run` prints it and stops, and apply walks it.
// One list, three readers: what you are shown is what runs.
package plan
import (
"errors"
"fmt"
"os"
"path/filepath"
"runtime"
"strings"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/deps"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/host"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/release"
)
// Component is one of the three programs.
type Component string
const (
Server Component = "server"
Console Component = "console"
Webmail Component = "webmail"
)
// Shape is how a component is installed here.
type Shape string
const (
Skip Shape = "skip"
Container Shape = "container"
Host Shape = "host"
)
// Names as they are shown to a person. The programs have names; the
// components have jobs.
var names = map[Component]string{
Server: "inbuxa-server (the mail server)",
Console: "inbuxa Admin (the console)",
Webmail: "inbuxa webmail",
}
// Choice is one row of the matrix.
type Choice struct {
Component Component
Shape Shape
}
// Options is everything the six screens collect.
type Options struct {
Domain string
MailHost string
ConsoleHost string
WebmailHost string
ACMEEmail string
Local bool // loopback evaluation: no public ports, no certificates
Dir string
Proxy string // "caddy", "snippets", "none"
Choices []Choice
InstallDeps bool // resolve what is missing rather than refusing over it
// A private ACME CA, for testing the certificate path without asking a
// public CA for certificates for names that are not ours. Empty means
// Let's Encrypt, which is what an install should use.
ACMEDirectory string
ACMECARoot string
// ServerURL is a mail server on another machine that the front ends here
// are joined to (`inbuxa join`); empty when the server is installed here.
ServerURL string
// Replace lets join put its front ends in place of others the server
// already lists.
Replace bool
// ExemptAddress is the address the server sees the webmail's requests
// come from, when it is not what the webmail's name resolves to.
ExemptAddress string
// Where this came from, when it came from a topology file: the machine's
// name in it, and the path, both recorded in the state file so a later
// run knows which part of which file this machine is.
Machine string
TopologyPath string
}
// Shape returns what was chosen for a component.
func (o Options) Shape(c Component) Shape {
for _, ch := range o.Choices {
if ch.Component == c {
return ch.Shape
}
}
return Skip
}
// Defaults fills in the names that follow from the domain, leaving anything
// the operator set alone.
func (o *Options) Defaults() {
if o.Domain == "" {
return
}
if o.MailHost == "" {
o.MailHost = "mail." + o.Domain
}
if o.ConsoleHost == "" {
o.ConsoleHost = "admin." + o.Domain
}
if o.WebmailHost == "" {
o.WebmailHost = "webmail." + o.Domain
}
if o.ACMEEmail == "" {
o.ACMEEmail = "postmaster@" + o.Domain
}
if o.Dir == "" {
o.Dir = "/var/lib/inbuxa"
}
if o.Proxy == "" {
o.Proxy = "caddy"
}
}
// Availability says whether a shape can be chosen for a component on this
// machine, and why not when it cannot. The interface dims what it cannot
// offer and shows the reason beside it; a flag that asks for it anyway gets
// the same sentence as an error.
type Availability struct {
OK bool
Why string
}
// ServerGlibc is the C library the published server binary is linked
// against. It is built in a current Debian, so a host install of the server
// needs a distribution at least this new -- Debian 13, Ubuntu 24.04, Fedora
// 40 and Arch all are; Rocky 9, Debian 12 and Ubuntu 22.04 are not, and on
// those the container shape is the answer rather than a binary that cannot
// start.
const (
ServerGlibcMajor = 2
ServerGlibcMinor = 39
)
// Available answers for one cell of the matrix: can this machine, as it is,
// deliver this component in this shape? Everything the interface offers and
// everything a flag will accept comes through here, so an offer is never
// made that the machine cannot keep.
func Available(f host.Facts, c Component, s Shape) Availability {
switch s {
case Skip:
return Availability{OK: true}
case Container:
if !f.Runtime.Present {
return Availability{Why: "no container runtime: neither docker nor podman is installed"}
}
if !f.Runtime.Usable {
return Availability{Why: f.Runtime.Why}
}
return Availability{OK: true}
case Host:
if !f.Systemd {
return Availability{Why: "a host install needs systemd, which is not running this machine"}
}
switch c {
case Server:
// The binary is downloaded, not built here, so the machine has
// to be able to run it.
if _, ok := release.ServerSHA256[runtime.GOARCH]; !ok {
return Availability{Why: fmt.Sprintf("inbuxa-server %s has no release binary for %s; run the server as a container here",
release.ServerVersion, runtime.GOARCH)}
}
if f.Glibc.Version == "" {
return Availability{Why: "this machine's C library could not be read, and the server binary is linked against glibc " +
fmt.Sprintf("%d.%d", ServerGlibcMajor, ServerGlibcMinor)}
}
if !f.Glibc.AtLeast(ServerGlibcMajor, ServerGlibcMinor) {
return Availability{Why: fmt.Sprintf(
"the server binary needs glibc %d.%d or newer and this machine has %s; run the server as a container here",
ServerGlibcMajor, ServerGlibcMinor, f.Glibc.Version)}
}
return Availability{OK: true}
case Console:
// Static files a web server serves: nothing runs, nothing to check
// on the machine but that there are files to install.
if release.ConsoleSHA256 == "" && os.Getenv("INBUXA_CONSOLE_TARBALL") == "" {
return Availability{Why: "no console release with files to install yet; run the console as a container"}
}
return Availability{OK: true}
case Webmail:
if _, ok := release.WebmailSHA256[runtime.GOARCH]; !ok && os.Getenv("INBUXA_WEBMAIL_TARBALL") == "" {
return Availability{Why: "no webmail release with files to install yet for " + runtime.GOARCH + "; run the webmail as a container"}
}
// Its own Node, which the installer fetches (deps): missing is an
// offer, not a refusal.
if f.Node.Path != host.OwnPath || f.Node.Major != deps.NodeMajor {
return Availability{Why: fmt.Sprintf("the webmail runs on the installer's own Node %d, in %s, which isn't there yet", deps.NodeMajor, filepath.Dir(filepath.Dir(host.OwnPath)))}
}
return Availability{OK: true}
}
}
return Availability{Why: "unknown shape"}
}
// Step is one thing the installer will do, in the order it will do it.
type Step struct {
Title string // shown as a line in the plan and ticked off during apply
Detail []string // the files, units, containers and ports it touches
}
// Plan is the whole of it.
type Plan struct {
Options Options
Steps []Step
Ports []int // what will be bound, once, across every component
DNS []string // records the domain needs for this shape
Warnings []string // things that are not refusals but should be read
Needs []deps.Need // what is missing, and what would be done about it
}
// Build works out what would happen. It does not touch the machine: every
// fact it needs is in the survey it was given.
func Build(f host.Facts, o Options) (Plan, error) {
o.Defaults()
p := Plan{Options: o}
if o.Domain == "" && !o.Local {
return p, fmt.Errorf("a domain is needed (or --local for a loopback evaluation)")
}
chosen, wantContainers, wantHostWebmail := 0, false, false
for _, c := range []Component{Server, Console, Webmail} {
switch o.Shape(c) {
case Skip:
case Container:
chosen++
wantContainers = true
case Host:
chosen++
if c == Webmail {
wantHostWebmail = true
}
}
}
if chosen == 0 {
return p, fmt.Errorf("nothing chosen: pick at least one component")
}
// The console on the host is files, and files need a web server: the
// managed Caddy, or yours with the configuration written for it.
if o.Shape(Console) == Host && (o.Local || o.Proxy == "none") {
return p, errors.New("the console on the host is static files, served by a web server: choose --proxy caddy or --proxy snippets, or run the console as a container" +
map[bool]string{true: " (a loopback evaluation has no web server)", false: ""}[o.Local])
}
// The proxy the installer manages is Caddy in a container, whatever the
// server is: a server on the host still needs a runtime for it.
if !o.Local && o.Proxy == "caddy" {
wantContainers = true
}
// What is missing is not the same as what is impossible. Docker absent on
// a Debian machine is one package and a service; Node too old is a pinned
// tarball. The installer says what it would do about each and does it when
// told, rather than handing the operator a chore and calling it an error.
p.Needs = deps.For(f, wantContainers, wantHostWebmail)
for _, c := range []Component{Server, Console, Webmail} {
s := o.Shape(c)
if s == Skip {
continue
}
a := Available(f, c, s)
if a.OK {
continue
}
if covered(p.Needs, c, s) && o.InstallDeps {
continue
}
if covered(p.Needs, c, s) {
return p, fmt.Errorf("%s as a %s install: %s\n\nThe installer can fix that:\n%s\nPass --install-deps to let it, or choose another shape",
names[c], s, a.Why, deps.Describe(p.Needs))
}
return p, fmt.Errorf("%s as a %s install: %s", names[c], s, a.Why)
}
if len(p.Needs) > 0 && o.InstallDeps {
var detail []string
for _, n := range p.Needs {
for _, a := range n.Actions {
detail = append(detail, n.Name+": "+a)
}
}
p.Steps = append(p.Steps, Step{Title: "Install what this machine is missing", Detail: detail})
}
if !f.Root {
p.Warnings = append(p.Warnings, "not running as root: installing units, users and files under /etc will fail")
}
if f.MemoryMB > 0 && f.MemoryMB < 2048 {
p.Warnings = append(p.Warnings, fmt.Sprintf("%d MB of memory: a mail server with a full text index wants 2 GB or more", f.MemoryMB))
}
if f.DiskFreeGB > 0 && f.DiskFreeGB < 10 {
p.Warnings = append(p.Warnings, fmt.Sprintf("%d GB free: mail, indexes and images need room to grow", f.DiskFreeGB))
}
if f.Existing != "" {
p.Warnings = append(p.Warnings, "an install is already recorded in "+f.Existing+": this run will converge it, not duplicate it")
}
p.Steps = append(p.Steps, Step{
Title: "Write the deployment directory",
Detail: []string{o.Dir + "/ (configuration, state and the credentials file)"},
})
if s := o.Shape(Server); s != Skip {
p.Ports = append(p.Ports, 25, 465, 993, 995, 4190)
switch s {
case Container:
p.Steps = append(p.Steps, Step{
Title: "Start the mail server as a container",
Detail: []string{
"image: " + release.ServerImage,
"volumes: inbuxa-data, inbuxa-etc",
"ports: 25, 465, 993, 995, 4190, and 8081 on loopback for the proxy",
},
})
case Host:
p.Steps = append(p.Steps, Step{
Title: "Install the mail server on this machine",
Detail: []string{
fmt.Sprintf("binary: /usr/local/bin/inbuxa-server, release %s for %s, checked against its pinned checksum",
release.ServerVersion, runtime.GOARCH),
"user: inbuxa (system, no login); configuration and data in " + o.Dir + "/server",
"unit: /etc/systemd/system/inbuxa-server.service, its environment in " + o.Dir + "/server.env",
"during setup it is reachable from this machine only; then its plain HTTP moves to 127.0.0.1:8081 and 443 is left to the proxy",
},
})
}
p.Steps = append(p.Steps, Step{
Title: "First boot",
Detail: []string{
"bootstrap over JMAP, then set the front-end URLs, which registers both first-party OAuth clients",
"turn on ACME, trust the proxy, create the first account",
"write " + o.Dir + "/credentials and " + o.Dir + "/dns.zone",
},
})
}
if s := o.Shape(Console); s != Skip {
switch s {
case Container:
p.Steps = append(p.Steps, Step{
Title: "Start the console as a container",
Detail: []string{
"image: registry.coffeylabs.org/inbuxa/inbuxa-admin (pinned to a release tag)",
"port: 8082 on loopback, behind the proxy",
},
})
case Host:
p.Steps = append(p.Steps, Step{
Title: "Install the console on this machine",
Detail: []string{
fmt.Sprintf("files: %s/console, from console release %s, checked against its pinned checksum", o.Dir, or(release.ConsoleVersion, "(a local tarball)")),
"served by " + map[string]string{"caddy": "the managed Caddy", "snippets": "your web server, from the configuration written for it"}[o.Proxy] + "; no service of its own: it is a page, not a program",
},
})
}
}
if s := o.Shape(Webmail); s != Skip {
switch s {
case Container:
p.Steps = append(p.Steps, Step{
Title: "Start the webmail as a container",
Detail: []string{
"image: registry.coffeylabs.org/inbuxa/inbuxa-webmail (pinned to a release tag)",
"port: 8080 on loopback, behind the proxy",
"secret: the OAuth client secret from first boot, written once",
},
})
case Host:
p.Steps = append(p.Steps, Step{
Title: "Install the webmail on this machine",
Detail: []string{
fmt.Sprintf("files: %s/webmail, from webmail release %s, checked against its pinned checksum; owned by root, read-only to the webmail", o.Dir, or(release.WebmailVersion, "(a local tarball)")),
fmt.Sprintf("Node %d: the installer's own, in /opt/inbuxa/node", deps.NodeMajor),
"user: inbuxa-webmail (system, no login)",
"unit: /etc/systemd/system/inbuxa-webmail.service, listening on 127.0.0.1:8080; its environment in " + o.Dir + "/webmail.env",
},
})
}
}
if !o.Local {
switch o.Proxy {
case "caddy":
p.Ports = append(p.Ports, 80, 443)
p.Steps = append(p.Steps, Step{
Title: "Put a proxy in front, with certificates",
Detail: []string{
"caddy, managed by the installer",
"names: " + strings.Join(o.hostnames(), ", "),
"ports: 80 and 443",
},
})
case "snippets":
p.Steps = append(p.Steps, Step{
Title: "Write proxy configuration for the web server already here",
Detail: []string{
o.Dir + "/proxy/nginx-inbuxa.conf and " + o.Dir + "/proxy/Caddyfile.fragment",
"nothing is loaded or restarted: that stays yours",
"the server trusts your web server's X-Forwarded-For and exempts it from the auto-ban",
"the mail server's own certificates: turned on in the console once it is loaded",
},
})
}
}
if o.ServerURL != "" {
detail := []string{"the server at " + o.ServerURL + ", with the API key given"}
if o.Shape(Console) != Skip {
detail = append(detail, "the console's address, which registers its OAuth client and allows its origin")
}
if o.Shape(Webmail) != Skip {
detail = append(detail,
"the webmail's address and a client secret generated here, kept in "+o.Dir+"/.env",
"this machine's address exempted from the server's auto-ban, as every webmail request comes from it")
}
p.Steps = append(p.Steps, Step{Title: "Register these front ends with the server (inbuxa:FrontEnds)", Detail: detail})
}
p.Steps = append(p.Steps, Step{
Title: "Check it works",
Detail: []string{
"the server answers JMAP and reports its version",
"each front end answers, and points at the server it was configured with",
"the ports that should be open are, and the ones that should not are not",
},
})
p.DNS = o.dnsRecords()
for _, held := range f.PortsHeld(p.Ports...) {
who := held.Holder
if who == "" {
who = "something this user cannot see"
}
p.Warnings = append(p.Warnings, fmt.Sprintf("port %d (%s) is held by %s", held.Number, held.For, who))
}
return p, nil
}
// covered says whether a cell's unavailability is one of the things the
// installer offered to fix.
func covered(needs []deps.Need, c Component, s Shape) bool {
want := map[string]bool{}
switch {
case s == Container:
want["docker"], want["compose"] = true, true
case s == Host && c == Webmail:
want["node"] = true
default:
return false
}
found := false
for _, n := range needs {
if !want[n.Name] {
continue
}
if !n.Fixable {
return false
}
found = true
}
return found
}
func (o Options) hostnames() []string {
var names []string
if o.Shape(Server) != Skip {
names = append(names, o.MailHost)
}
if o.Shape(Console) != Skip {
names = append(names, o.ConsoleHost)
}
if o.Shape(Webmail) != Skip {
names = append(names, o.WebmailHost)
}
return names
}
func (o Options) dnsRecords() []string {
if o.Local || o.Domain == "" {
return nil
}
var r []string
if o.Shape(Server) != Skip {
r = append(r,
fmt.Sprintf("%-28s MX 10 %s.", o.Domain+".", o.MailHost),
fmt.Sprintf("%-28s A this machine", o.MailHost+"."),
fmt.Sprintf("%-28s TXT \"v=spf1 mx -all\"", o.Domain+"."),
fmt.Sprintf("%-28s TXT the DKIM key first boot generates", "*._domainkey."+o.Domain+"."),
fmt.Sprintf("%-28s TXT \"v=DMARC1; p=reject; rua=mailto:postmaster@%s\"", "_dmarc."+o.Domain+".", o.Domain),
)
}
if o.Shape(Console) != Skip {
r = append(r, fmt.Sprintf("%-28s A this machine", o.ConsoleHost+"."))
}
if o.Shape(Webmail) != Skip {
r = append(r, fmt.Sprintf("%-28s A this machine", o.WebmailHost+"."))
}
r = append(r, "(first boot writes the exact records, including the keys, to dns.zone)")
return r
}
// String renders the plan the way the fifth screen and --dry-run show it.
func (p Plan) String() string {
var b strings.Builder
o := p.Options
fmt.Fprintf(&b, "Plan for %s\n\n", describe(o))
for i, s := range p.Steps {
fmt.Fprintf(&b, "%2d. %s\n", i+1, s.Title)
for _, d := range s.Detail {
fmt.Fprintf(&b, " %s\n", d)
}
}
if len(p.Ports) > 0 {
fmt.Fprintf(&b, "\nPorts it will bind: %s\n", joinInts(p.Ports))
}
if len(p.DNS) > 0 {
b.WriteString("\nThe domain will need:\n")
for _, r := range p.DNS {
fmt.Fprintf(&b, " %s\n", r)
}
}
if len(p.Warnings) > 0 {
b.WriteString("\nWorth reading first:\n")
for _, w := range p.Warnings {
fmt.Fprintf(&b, " - %s\n", w)
}
}
return b.String()
}
func describe(o Options) string {
var parts []string
for _, c := range []Component{Server, Console, Webmail} {
if s := o.Shape(c); s != Skip {
parts = append(parts, fmt.Sprintf("%s as a %s install", names[c], s))
}
}
where := o.Domain
if o.Local {
where = "a loopback evaluation"
}
if o.ServerURL != "" {
where += ", joined to " + o.ServerURL
}
return strings.Join(parts, ", ") + " -- " + where
}
func joinInts(n []int) string {
seen := map[int]bool{}
var out []string
for _, i := range n {
if seen[i] {
continue
}
seen[i] = true
out = append(out, fmt.Sprint(i))
}
return strings.Join(out, ", ")
}
func or(a, b string) string {
if a != "" {
return a
}
return b
}