`inbuxa join https://mail.example.com --key KEY` installs the front ends on this machine for a mail server already running on another one. That server is reached only over its own HTTPS, with an API key a server administrator made in the console (--key -, or INBUXA_JOIN_KEY, keeps it out of the shell's history; it is never written down). Through it the front ends' addresses and a webmail client secret made here go into the server's inbuxa:FrontEnds (server #195), which registers their sign-in and allows the console's origin on every node, with no restart and nothing done by hand on that machine. It asks first, dry runs included, and refuses with the reason when the key is wrong, the server has no inbuxa:FrontEnds, it already lists other front ends (--replace), or its environment owns the webmail's secret. Then it installs the console and the webmail in containers with Caddy, registers them, exempts the webmail's address from the server's auto-ban (what its name resolves to, loopback for a loopback server, or --exempt-address), and checks that the server lets the console call it. A second join with the same addresses converges. The compose file learns a server elsewhere: the webmail reaches it at its address, and Caddy serves only the front ends' names. Container and host-server installs render as before. INBUXA_SERVER_BINARY installs a server build instead of the release wherever the server goes on the host, for testing a server change before it is released; e2e/vm/run.sh passes one in with SERVER_BINARY=. e2e/cases/join.sh: 24 checks on Debian 13 against a build of server #195, ending with a person signing in to the joined webmail. install-local, install-host, install-public, status-export and topology pass unchanged.
559 lines
17 KiB
Go
559 lines
17 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 (
|
|
"fmt"
|
|
"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 behind whatever serves them: nothing to run.
|
|
return Availability{OK: true}
|
|
case Webmail:
|
|
if !f.Node.Present {
|
|
return Availability{Why: "a host install of the webmail needs Node 22 or newer; none is installed"}
|
|
}
|
|
if f.Node.Major < 22 {
|
|
return Availability{Why: fmt.Sprintf("a host install of the webmail needs Node 22 or newer; found %s", f.Node.Version)}
|
|
}
|
|
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 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{
|
|
"files: " + o.Dir + "/console (static, served by the proxy)",
|
|
"no service: 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{
|
|
"files: " + o.Dir + "/webmail, from the release tarball",
|
|
"user: inbuxa-webmail (system, no login)",
|
|
"unit: /etc/systemd/system/inbuxa-webmail.service, listening on 127.0.0.1:8080",
|
|
},
|
|
})
|
|
}
|
|
}
|
|
|
|
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",
|
|
},
|
|
})
|
|
}
|
|
}
|
|
|
|
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, ", ")
|
|
}
|