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.
555 lines
17 KiB
Go
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, ", ")
|
|
}
|