Files
inbuxa-installer/internal/plan/plan.go
T
jcoffey-dev 35172dd0f5 --proxy snippets writes what it promised: nginx and Caddy configuration
The plan, the usage text and the docs all said --proxy snippets writes
configuration for the web server already on the machine; nothing did. Now
it writes <dir>/proxy/nginx-inbuxa.conf and <dir>/proxy/Caddyfile.fragment:
the server's names, the console and the webmail passed to their loopback
ports, X-Forwarded-For set to the client's address, the webmail's and the
server's push streams unbuffered, port 80 passing the mail server's own
certificate challenges to it and redirecting the rest. The fragment has no
global block, so it imports beside other sites, and leaves HTTP-01 for the
server's names to the server, as the managed Caddy does.

That web server becomes the proxy, so it is treated as Caddy is: the
server trusts its X-Forwarded-For and exempts the address its requests
arrive from -- loopback for a server on the host, the project network's
gateway too for one in a container, where a published loopback port is
reached from there. Nothing is loaded or reloaded; the summary names the
directory, and the mail server's own certificates are turned on in the
console once the file is loaded. A re-run rewrites it for what is
installed then.

The interface's Reach screen offers it, beside Caddy and nothing in front.

Tests: the snippets render for each shape and leave out what isn't
installed; they pass `nginx -t` and `caddy validate`.
e2e/cases/proxy-snippets.sh installs nginx, installs behind it, loads the
written file and reaches the server, console and webmail through it on
443, with port 80 passing a challenge to the server and redirecting the
console: 13/13. interface, install-local, install-host, install-public,
status-export and topology pass unchanged.
2026-10-12 09:48:25 -07:00

555 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:
return Availability{Why: "not built yet: the console runs in a container for now"}
case Webmail:
// Phase 2: a unit with a pinned Node (deps already fetches one).
return Availability{Why: "not built yet: the webmail runs in a container for now"}
}
}
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",
"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, ", ")
}