Files
jcoffey-dev fabffd5161
ci / test (pull_request) Successful in 51s
Install: pin Caddy by digest
The proxy in front of the console and the webmail, which holds their
TLS keys (and runs on the host network beside a host server), was
docker.io/library/caddy:2-alpine: a floating tag on Docker Hub, so
every install and converge ran whatever that tag named that day, and
whoever could push it chose what ran as the proxy. Everything else
the installer downloads is checked against a checksum in its source.

Caddy is now pinned in internal/release by the digest of its image
index (2.11.9-alpine, the same digest as on main), and compose.yaml
names it by digest. The comment that called the suite's own tags
immutable is corrected: they can be pushed again.

Backport to the 2026 line, by hand where the code differs: this line
has no pin-check, so that part is left out and the pin is moved by
hand like the other pins here; the image test also accepts the
webmail's version-and-commit tags.

Test: TestCaddyIsPinnedByDigest failed before (DefaultCaddyImage was
"docker.io/library/caddy:2-alpine") and now passes;
TestSuiteImagesNameAnExactRelease is new.

(backported from commit 71ec74be74)
2026-11-17 16:13:28 -07:00

1033 lines
37 KiB
Go
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
// Package apply carries out a plan: every component in a container, or the
// mail server on the host with whatever runs beside it in containers.
//
// The sequence is SPEC.md 6.2's, which ihasmail-oneshot worked out against a
// running server: bring the mail server up in bootstrap mode with a
// credential that exists only for this step, complete bootstrap, bring the
// rest of the stack up without that credential, exempt the front ends from
// the auto-ban, restart so the settings take, create the first account, and
// write down what nobody can recover later.
//
// Every step is one of the plan's steps, in the plan's order. A step that
// fails stops the run with the service's own last lines, because "compose
// exited 1" is not a reason.
package apply
import (
"context"
"crypto/rand"
"fmt"
"io"
"math/big"
"net/http"
"net/url"
"os"
"os/exec"
"path/filepath"
"strconv"
"strings"
"time"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/compose"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/deps"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/discover"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/docker"
"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/release"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state"
)
// Images are the defaults. The suite's own name one release each, by tag:
// the registry is ours, but its tags can be pushed again by anyone holding a
// push token, so they are a release's name rather than a guarantee of its
// contents. Caddy, from Docker Hub, is pinned by digest (release.CaddyImage).
const (
DefaultServerImage = release.ServerImage
DefaultConsoleImage = "registry.coffeylabs.org/inbuxa/inbuxa-admin:" + release.ConsoleVersion
DefaultWebmailImage = "registry.coffeylabs.org/inbuxa/inbuxa-webmail:" + release.WebmailVersion
DefaultCaddyImage = release.CaddyImage
DefaultSubnet = "172.31.253.0/24"
// DefaultIPv6Subnet is a unique local /64 for the same network, on a
// machine with IPv6 (#65). Nothing outside the machine ever sees it.
DefaultIPv6Subnet = "fd69:6e62:7578::/64"
)
// Result is what the operator is left holding.
type Result struct {
Dir string
AdminUser string
AdminPass string
FirstUser string
FirstPass string
ZoneFile string
Certificate string // what issued the mail server's certificate, when one arrived
ProxyConfig string // where the configuration for the operator's own web server is, with --proxy snippets
ConsoleURL string
WebmailURL string
ServerURL string
}
// Log is how apply reports progress. The interface will draw ticks from it;
// the flag path prints it.
type Log interface {
Step(format string, a ...any)
Info(format string, a ...any)
Out() io.Writer
}
// Run carries out p: each component in a container or on the host, as the
// plan says.
func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, error) {
o := p.Options
if o.Shape(plan.Server) == plan.Skip {
return nil, fmt.Errorf("this build installs the front ends only alongside a server it installs too; use join once that is built")
}
onHost := o.Shape(plan.Server) == plan.Host
var moveFrom plan.Shape
if st, err := state.Load(); err == nil {
moveFrom, _ = MovingServer(st, o)
}
needContainers := !onHost || o.Shape(plan.Console) == plan.Container ||
o.Shape(plan.Webmail) == plan.Container || (!o.Local && o.Proxy == "caddy")
if len(p.Needs) > 0 && o.InstallDeps {
log.Step("installing what this machine is missing")
if err := deps.Resolve(ctx, log.Out(), p.Needs); err != nil {
return nil, err
}
// The survey was taken before any of that existed. Installing podman
// on a machine that had no runtime and then driving the deployment
// with the old facts meant reaching for a docker that was never
// going to be there.
f = host.Survey(ctx)
if needContainers && !f.Runtime.Usable {
return nil, fmt.Errorf("after installing what was missing, containers still are not usable: %s", f.Runtime.Why)
}
if needContainers {
log.Info("using %s %s", f.Runtime.Kind, f.Runtime.Version)
}
}
// A move stops the old shape and archives it before anything of the
// new one is written; it is carried out once that is in place.
var mv *serverMove
if moveFrom != "" {
var err error
if mv, err = beginMove(ctx, o, moveFrom, f, log); err != nil {
return nil, err
}
// Whatever stops this run before the move is carried out puts the
// old shape back; finish does its own putting back.
defer mv.abort(ctx)
}
dir := o.Dir
stack := compose.Stack{
Version: "dev",
Project: "inbuxa",
Server: !onHost,
HostServer: onHost,
Domain: o.Domain,
Email: o.ACMEEmail,
Local: o.Local,
MailHost: o.MailHost,
ConsoleHost: o.ConsoleHost,
WebmailHost: o.WebmailHost,
Console: o.Shape(plan.Console) == plan.Container,
Webmail: o.Shape(plan.Webmail) == plan.Container,
WebmailUnit: o.Shape(plan.Webmail) == plan.Host,
Proxy: !o.Local && o.Proxy == "caddy",
ServerImage: DefaultServerImage,
ConsoleImage: DefaultConsoleImage,
WebmailImage: DefaultWebmailImage,
CaddyImage: DefaultCaddyImage,
ServerBind: "127.0.0.1:8081",
ConsoleBind: "127.0.0.1:8082",
WebmailBind: "127.0.0.1:8080",
Subnet: DefaultSubnet,
}
if f.IPv6 {
stack.IPv6Subnet = DefaultIPv6Subnet
}
if o.Local {
// Nothing is published and nothing is certified: the addresses are
// the loopback binds, which is what the front ends are told to use.
stack.ServerPublicURL = "http://127.0.0.1:8081"
if o.Shape(plan.Console) != plan.Skip {
stack.ConsoleURL = "http://127.0.0.1:8082"
}
if o.Shape(plan.Webmail) != plan.Skip {
stack.WebmailURL = "http://127.0.0.1:8080"
}
} else {
stack.MailPorts = []int{25, 465, 993, 995, 4190}
stack.ServerPublicURL = "https://" + o.MailHost
if o.Shape(plan.Console) != plan.Skip {
stack.ConsoleURL = "https://" + o.ConsoleHost
}
if o.Shape(plan.Webmail) != plan.Skip {
stack.WebmailURL = "https://" + o.WebmailHost
}
}
// A private ACME CA has to be trusted by two programs that never see each
// other's trust store: the mail server, which asks for its own
// certificate over HTTP-01, and Caddy, which asks for the front ends'.
// The server gets the image's own roots plus this one as a file it mounts
// over its bundle; Caddy gets the root on its own.
if o.ACMECARoot != "" {
root, err := os.ReadFile(o.ACMECARoot)
if err != nil {
return nil, fmt.Errorf("reading the ACME CA root: %w", err)
}
if err := os.MkdirAll(dir, 0o750); err != nil {
return nil, err
}
var bundle []byte
if onHost {
bundle, err = systemCABundle()
} else {
bundle, err = docker.SystemCABundle(ctx, stack.ServerImage)
}
if err != nil {
return nil, fmt.Errorf("reading the server's CA bundle: %w", err)
}
if err := os.WriteFile(filepath.Join(dir, "ca-bundle.crt"), append(bundle, root...), 0o644); err != nil {
return nil, err
}
if err := os.WriteFile(filepath.Join(dir, "acme-ca-root.pem"), root, 0o644); err != nil {
return nil, err
}
stack.CABundle = true
stack.ACMECARoot = "acme-ca-root.pem"
}
stack.ACMEDirectory = o.ACMEDirectory
if o.Shape(plan.Console) == plan.Host {
stack.ConsoleFiles = hostConsole{deploy: dir}.dir()
}
log.Step("writing the deployment into %s", dir)
var sec compose.Secrets
var err error
if stack.Empty() {
if sec, err = compose.EnsureSecrets(dir); err != nil {
return nil, err
}
log.Info(".env (nothing runs in containers here)")
} else {
if sec, err = compose.Write(dir, &stack); err != nil {
return nil, err
}
log.Info("compose.yaml, .env%s", map[bool]string{true: " and Caddyfile", false: ""}[stack.Proxy])
}
// Whichever runtime the survey found: docker where there is one, podman
// on the Red Hat family, driven through the same compose plugin.
docker.UseRuntime(f.Runtime)
cmp := docker.Compose{Dir: dir, Runtime: f.Runtime}
if !stack.Empty() {
log.Step("fetching the images")
if err := cmp.Run(ctx, "pull", "--quiet"); err != nil {
return nil, err
}
}
// The server on the host: what a container would have brought with it.
var hs *hostServer
var srvLogs logSource = cmp
// Whether the binary or its environment changed under a server that is
// already running, which only a restart makes it see.
serverChanged := false
if onHost {
hs = &hostServer{deploy: dir, log: log}
srvLogs = hs
log.Step("installing the mail server on this machine")
replaced, err := hs.Install(ctx)
if err != nil {
return nil, err
}
envChanged, err := hs.WriteEnv(serverEnv(o, stack, sec))
if err != nil {
return nil, err
}
serverChanged = replaced || envChanged
log.Info("%s, %s", hostUnitPath, hs.envPath())
}
// The front ends on the host: in place before anything starts, the
// console's files because the proxy serves them from the moment it is
// up, the webmail because its unit starts with the rest of the stack.
var hw *hostWebmail
webmailEnvChanged := false
if o.Shape(plan.Webmail) != plan.Host {
// A webmail moved off the host gives its port back before a
// container wants it.
if _, err := os.Stat(webmailUnitPath); err == nil {
log.Info("stopping the webmail installed on the host, which is no longer asked for")
runQuiet(ctx, "systemctl", "disable", "--now", "--quiet", HostWebmailUnit)
}
}
if o.Shape(plan.Console) == plan.Host {
if err := (hostConsole{deploy: dir, log: log}).Install(ctx, stack.ServerPublicURL); err != nil {
return nil, err
}
}
if o.Shape(plan.Webmail) == plan.Host {
hw = &hostWebmail{deploy: dir, log: log}
if err := hw.Install(ctx); err != nil {
return nil, err
}
if webmailEnvChanged, err = hw.WriteEnv(webmailEnv(o, stack, sec, hw.Version())); err != nil {
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() {
if mv != nil {
if err := mv.finish(ctx, stack, !o.Local && o.Proxy == "snippets"); err != nil {
return nil, err
}
// What it reads at start has been read: nothing more to restart for.
serverChanged = false
}
res, err := converge(ctx, o, stack, cmp, hs, serverChanged, existing, f, log)
if err == nil && hw != nil {
// Its files may be new, or what it reads at start; or it may
// simply not be running.
active := exec.CommandContext(ctx, "systemctl", "is-active", "--quiet", HostWebmailUnit).Run() == nil
if webmailEnvChanged || !active || existing.Shapes["webmail"] != string(plan.Host) {
if err := hw.Start(ctx); err != nil {
return res, withLogs(ctx, err, hw, "webmail")
}
}
}
if err == nil && !o.Local && o.Proxy == "snippets" {
// What the web server is told follows what is installed here.
if dir, err := compose.WriteProxySnippets(o.Dir, stack); err == nil {
res.ProxyConfig = dir
log.Info("rewrote %s for what is installed now: reload your web server if it changed", dir)
}
}
return res, err
}
// 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
// fixed recovery credential outlives the setup.
bootPass, err := password(24)
if err != nil {
return nil, err
}
override, cleanup, err := setupOverride("inbuxa-bootstrap.yaml",
"services:\n server:\n environment:\n INBUXA_RECOVERY_ADMIN: ${INBUXA_BOOTSTRAP_ADMIN:?}\n")
if err != nil {
return nil, err
}
defer cleanup()
log.Step("starting the mail server in bootstrap mode")
serverURL := "http://" + stack.ServerBind
if onHost {
// Its default listeners until they are fitted to the host, behind a
// drop-in that keeps everything but loopback out meanwhile.
serverURL = hostSetupBind
if _, err := hs.WriteUnit(ctx, false); err != nil {
return nil, err
}
if err := hs.Start(ctx, modeBootstrap, bootPass); err != nil {
return nil, withLogs(ctx, err, srvLogs, "server")
}
} else {
boot := cmp
boot.Files = []string{override}
boot.Env = []string{"INBUXA_BOOTSTRAP_ADMIN=admin:" + bootPass}
if err := boot.Run(ctx, "up", "-d", "server"); err != nil {
return nil, err
}
}
if err := waitFor(ctx, log, "the mail server", 120*time.Second, func(ctx context.Context) error {
return live(ctx, serverURL)
}); err != nil {
return nil, withLogs(ctx, err, srvLogs, "server")
}
bootClient := setupClient(onHost, jmap.Client{BaseURL: serverURL, Username: "admin", Password: bootPass})
if err := bootClient.CheckBootstrapMode(ctx); err != nil {
return nil, err
}
log.Step("setting up %s (hostname %s)", o.Domain, o.MailHost)
dataPath := ""
if onHost {
dataPath = hs.DataPath()
}
admin, err := bootClient.Bootstrap(ctx, o.MailHost, o.Domain, dataPath)
if err != nil {
return nil, fmt.Errorf("bootstrap: %w", err)
}
res := &Result{
Dir: dir, AdminUser: admin.Username, AdminPass: admin.Secret,
ConsoleURL: stack.ConsoleURL, WebmailURL: stack.WebmailURL, ServerURL: stack.ServerPublicURL,
}
// Written now, not at the end: from this moment the password exists
// nowhere else, and a failure in a later step must not lose it.
if err := writeCredentials(dir, res); err != nil {
return res, err
}
log.Info("administrator %s, password in %s", admin.Username, filepath.Join(dir, "credentials.txt"))
// Once configured, the server takes a token, never a password, on /jmap
// (contract C-23), and the bootstrap credential no longer works; nor
// does anything but x:Bootstrap work before then. So the server comes up
// configured with Basic allowed, for this one step only, long enough for
// the administrator to give itself an API key with its password. The key
// does the rest of the setup, is removed when the setup ends, and expires
// within the hour anyway, so a setup that stops halfway leaves nothing
// that still works.
basicOverride, cleanupBasic, err := setupOverride("inbuxa-basic-auth.yaml",
"services:\n server:\n environment:\n INBUXA_HTTP_BASIC_AUTH: all\n")
if err != nil {
return res, err
}
defer cleanupBasic()
log.Step("restarting the mail server configured, to give the setup an API key")
if onHost {
if err := hs.Start(ctx, modeBasic, ""); err != nil {
return res, withLogs(ctx, err, srvLogs, "server")
}
} else {
basic := cmp
basic.Files = []string{basicOverride}
if err := basic.Run(ctx, "up", "-d", "server"); err != nil {
return res, err
}
}
adminBasic := setupClient(onHost, jmap.Client{BaseURL: serverURL, Username: admin.Username, Password: admin.Secret})
var keyID, key string
if err := waitFor(ctx, log, "the server to come back configured", 120*time.Second, func(ctx context.Context) error {
var err error
keyID, key, err = adminBasic.CreateAPIKey(ctx, "inbuxa installer, for this setup only", time.Hour)
return err
}); err != nil {
return res, withLogs(ctx, fmt.Errorf("an API key for the setup: %w", err), srvLogs, "server")
}
srv := setupClient(onHost, jmap.Client{BaseURL: serverURL, Token: key})
defer func() {
ctx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
defer cancel()
if err := srv.DestroyAPIKey(ctx, keyID); err != nil {
log.Info("could not remove the setup's API key, which expires within the hour: %v", err)
}
}()
if onHost {
log.Step("fitting the server's listeners to the host")
if err := srv.HostListeners(ctx, hostFinalBind, o.Local); err != nil {
return res, fmt.Errorf("moving the server's listeners: %w", err)
}
log.Info("plain HTTP on %s for the proxy and the webmail; 443 is left to the proxy", hostFinalBind)
if o.Local {
log.Info("the mail ports on loopback only")
}
if _, err := hs.WriteUnit(ctx, true); err != nil {
return res, err
}
if err := hs.Start(ctx, modeNormal, ""); err != nil {
return res, withLogs(ctx, err, srvLogs, "server")
}
serverURL = "http://" + hostFinalBind
srv.BaseURL = serverURL
}
log.Step("starting the rest of the stack")
// Without the override, so the server is recreated taking tokens only.
// --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 !stack.Empty() {
if err := cmp.Run(ctx, "up", "-d", "--remove-orphans"); err != nil {
return res, err
}
}
if hw != nil {
if err := hw.Start(ctx); err != nil {
return res, withLogs(ctx, err, hw, "webmail")
}
}
if err := waitFor(ctx, log, "the server to come back configured", 120*time.Second, func(ctx context.Context) error {
_, err := srv.DomainID(ctx, o.Domain)
return err
}); err != nil {
return res, withLogs(ctx, err, srvLogs, "server")
}
domainID, err := srv.DomainID(ctx, o.Domain)
if err != nil {
return res, err
}
// Every request the webmail makes arrives from one address: every
// sign-in, every push stream opened and dropped as tabs come and go. The
// server bans per address, so a ban on that one is a ban on everybody's
// webmail. The webmail rate-limits sign-ins per real client itself.
// On the host both arrive from loopback, which is exempted once.
allowed := map[string]bool{}
if stack.Webmail {
log.Step("exempting the webmail from the auto-ban")
if err := srv.AllowIP(ctx, stack.WebmailIP, "the webmail: every request arrives from this address"); err != nil {
return res, fmt.Errorf("exempting the webmail: %w", err)
}
allowed[stack.WebmailIP] = true
}
if stack.Proxy {
log.Step("trusting the proxy's X-Forwarded-For")
if err := srv.TrustForwardedFor(ctx); err != nil {
return res, fmt.Errorf("trusting the proxy: %w", err)
}
if !allowed[stack.CaddyIP] {
if err := srv.AllowIP(ctx, stack.CaddyIP, "the proxy: certificate renewals and autoconfig arrive from this address"); err != nil {
return res, fmt.Errorf("exempting the proxy: %w", err)
}
}
}
// The operator's own web server, in front of the same loopback ports:
// trusted the same way, and exempted at the address its requests
// arrive from. That is loopback for a server on the host; for one in a
// container it is the project network's gateway, because a request to
// a published loopback port reaches the container from there.
snippets := !o.Local && o.Proxy == "snippets"
if snippets {
log.Step("trusting your web server's X-Forwarded-For")
if err := srv.TrustForwardedFor(ctx); err != nil {
return res, fmt.Errorf("trusting the proxy: %w", err)
}
from := []string{"127.0.0.1"}
if !onHost {
from = append(from, stack.GatewayIP)
}
for _, addr := range from {
if allowed[addr] {
continue
}
if err := srv.AllowIP(ctx, addr, "your web server in front of the suite: its requests arrive from this address"); err != nil {
return res, fmt.Errorf("exempting your web server: %w", err)
}
allowed[addr] = true
}
}
if stack.Webmail || stack.Proxy || snippets {
// Neither setting takes effect on a running server.
log.Info("restarting the server so those take effect")
restart := func() error { return cmp.Run(ctx, "restart", "server") }
if onHost {
restart = func() error { return hs.Restart(ctx) }
}
if err := restart(); err != nil {
return res, err
}
if err := waitFor(ctx, log, "the server to restart", 120*time.Second, func(ctx context.Context) error {
_, err := srv.DomainID(ctx, o.Domain)
return err
}); err != nil {
return res, withLogs(ctx, err, srvLogs, "server")
}
}
// 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 snippets {
log.Step("writing the configuration for your web server")
dir, err := compose.WriteProxySnippets(o.Dir, stack)
if err != nil {
return res, fmt.Errorf("writing the proxy configuration: %w", err)
}
res.ProxyConfig = dir
log.Info("%s/nginx-inbuxa.conf and %s/Caddyfile.fragment: load one into your web server", dir, dir)
log.Info("once it is loaded, turn on the mail server's own certificates in the console (Settings › Overview, Certificates): its challenges reach it through port 80")
} else 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)
}
// An order that fails is not retried on its own, and a restart does
// not start a new one: moving the domain to manual and back is what
// does. So this waits, and asks again every so often, rather than
// declaring the install finished over a self-signed certificate that
// every mail client will refuse.
if issuer := waitForCertificate(ctx, srv, log, domainID, o.MailHost, 3*time.Minute); issuer != "" {
res.Certificate = issuer
log.Info("certificate for %s issued by %s", o.MailHost, issuer)
} else {
log.Info("no certificate yet for %s: the server keeps trying, and will succeed once %s resolves to this machine and port 80 reaches it",
o.MailHost, o.MailHost)
}
}
log.Step("creating the first account")
first := "postmaster"
pass, err := password(20)
if err != nil {
return res, err
}
if _, err := srv.CreateUser(ctx, first, domainID, pass); err != nil {
return res, fmt.Errorf("creating %s@%s: %w", first, o.Domain, err)
}
res.FirstUser, res.FirstPass = first+"@"+o.Domain, pass
if err := writeCredentials(dir, res); err != nil {
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, st.MailHost, st.Local = o.Machine, dir, o.Domain, o.MailHost, o.Local
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")
if err := os.WriteFile(res.ZoneFile, []byte(zone), 0o644); err != nil {
return res, err
}
log.Info("the records this domain needs are in %s", res.ZoneFile)
}
return res, nil
}
// waitForCertificate waits for the mail server's own certificate to arrive,
// asking for a fresh order every 45 seconds. It returns the issuer, or ""
// when none arrived in time -- which is not a failure: on a real install the
// domain often does not point here yet, and the server goes on trying.
func waitForCertificate(ctx context.Context, srv *jmap.Client, log Log, domainID, host string, limit time.Duration) string {
deadline := time.Now().Add(limit)
nextRetry := time.Now().Add(45 * time.Second)
for time.Now().Before(deadline) {
certs, err := srv.Certificates(ctx)
if err == nil {
for _, c := range certs {
if c.SubjectAlternativeNames[host] && !strings.Contains(c.Issuer, "self signed") {
return c.Issuer
}
}
}
if time.Now().After(nextRetry) {
log.Info("asking for the certificate again")
_ = srv.RetryCertificates(ctx, domainID)
nextRetry = time.Now().Add(45 * time.Second)
}
select {
case <-ctx.Done():
return ""
case <-time.After(3 * time.Second):
}
}
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, hs *hostServer,
serverChanged bool, 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]
}
}
}
if hs != nil {
return convergeHost(ctx, o, stack, cmp, hs, serverChanged, st, f, log, res)
}
// Before anything is recreated: an install from before #5 keeps the
// server's data where the corrected compose file no longer mounts it.
moved, err := adoptServerVolumes(ctx, cmp, stack.Project, log)
if err != nil {
return res, err
}
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")
}
if moved {
// A server that finds no configuration starts in bootstrap mode and
// says so. That would mean the move missed something; the old
// volumes are still there to put back.
if err := waitFor(ctx, log, "the server to come back on its named volumes", 120*time.Second, func(ctx context.Context) error {
return live(ctx, "http://"+stack.ServerBind)
}); err != nil {
return res, withLogs(ctx, err, cmp, "server")
}
if strings.Contains(cmp.Logs(ctx, "server", 400), "bootstrap mode") {
return res, fmt.Errorf("the server came back in bootstrap mode after its data was moved; " +
"its previous volumes are untouched, see `docker volume ls` and issue #5")
}
log.Info("the server came back with its configuration")
}
// 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")
}
}
saveState(st, o, f, log)
return res, nil
}
// convergeHost is converge for a server on the host: the binary, the unit
// and its environment are rewritten if they changed, whatever runs in
// containers beside it is brought in line, and the server is restarted only
// if what it reads at start is different. serverChanged is Run's word on the
// binary and the environment, which it wrote before getting here.
func convergeHost(ctx context.Context, o plan.Options, stack compose.Stack, cmp docker.Compose, hs *hostServer,
serverChanged bool, st *state.State, f host.Facts, log Log, res *Result) (*Result, error) {
unitChanged, err := hs.WriteUnit(ctx, true)
if err != nil {
return res, err
}
log.Step("bringing the stack in line with the file")
if stack.Empty() {
if _, err := os.Stat(filepath.Join(o.Dir, "compose.yaml")); err == nil {
// Everything that ran beside the server was removed.
if err := cmp.Run(ctx, "down", "--remove-orphans"); err != nil {
return res, err
}
os.Remove(filepath.Join(o.Dir, "compose.yaml"))
os.Remove(filepath.Join(o.Dir, "Caddyfile"))
}
} else if err := cmp.Run(ctx, "up", "-d", "--remove-orphans"); err != nil {
return res, err
}
_, active := discover.HostServer(ctx)
frontEnds := st.Shapes["console"] != string(o.Shape(plan.Console)) || st.Shapes["webmail"] != string(o.Shape(plan.Webmail))
if frontEnds || serverChanged || unitChanged || !active {
log.Info("restarting the server")
if err := hs.Restart(ctx); err != nil {
return res, withLogs(ctx, err, hs, "server")
}
if err := waitFor(ctx, log, "the server to answer again", 120*time.Second, func(ctx context.Context) error {
return live(ctx, "http://"+hostFinalBind)
}); err != nil {
return res, withLogs(ctx, err, hs, "server")
}
}
saveState(st, o, f, log)
return res, nil
}
func saveState(st *state.State, o plan.Options, f host.Facts, log Log) {
st.Machine, st.Dir, st.Domain, st.MailHost, st.Local = o.Machine, o.Dir, o.Domain, o.MailHost, o.Local
st.Runtime, st.Topology = f.Runtime.Kind, o.TopologyPath
st.Installer = "server " + release.ServerVersion
st.RemovedAt = nil // installed again, on what was kept
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)
}
}
// verifyFor is how long Verify gives each check.
var verifyFor = time.Minute
// Verify is the last step: does what was installed actually answer?
func Verify(ctx context.Context, res *Result, o plan.Options, server bool, log Log) []string {
var problems []string
// Each for up to a minute: a container started a moment ago -- the
// last thing a converge does -- can refuse a connection before it
// answers, and that is not a problem to report.
check := func(what, url string, want string) {
var last string
deadline := time.Now().Add(verifyFor)
for {
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
resp, err := (&http.Client{}).Do(req)
if err == nil {
body, _ := io.ReadAll(io.LimitReader(resp.Body, 64<<10))
resp.Body.Close()
if want == "" || strings.Contains(string(body), want) {
cancel()
log.Info("%s answers", what)
return
}
last = fmt.Sprintf("%s answered at %s but did not look like itself", what, url)
} else {
last = fmt.Sprintf("%s did not answer at %s: %v", what, url, err)
}
cancel()
if time.Now().After(deadline) {
problems = append(problems, last)
return
}
time.Sleep(2 * time.Second)
}
}
if server {
check("the mail server", "http://127.0.0.1:8081/.well-known/jmap", "")
}
switch o.Shape(plan.Console) {
case plan.Container:
check("the console", "http://127.0.0.1:8082/", "api-base-url")
case plan.Host:
// Files, served by a web server that may not be loaded yet: what
// can be checked here is that they are in place and name the
// server.
index := filepath.Join(o.Dir, "console", "index.html")
b, err := os.ReadFile(index)
switch {
case err != nil:
problems = append(problems, "the console's files are missing: "+err.Error())
case !strings.Contains(string(b), `name="api-base-url" content="`+res.ServerURL+`"`):
problems = append(problems, index+" does not point at "+res.ServerURL)
default:
log.Info("the console's files are in place, pointed at %s", res.ServerURL)
}
}
if o.Shape(plan.Webmail) != plan.Skip {
check("the webmail", "http://127.0.0.1:8080/api/health", "\"ok\":true")
}
return problems
}
func writeCredentials(dir string, r *Result) error {
var b strings.Builder
b.WriteString("# inbuxa -- written by the installer. Keep this file.\n")
b.WriteString("# The administrator's password is not recoverable: nothing else holds it.\n\n")
fmt.Fprintf(&b, "administrator %s\npassword %s\n", r.AdminUser, r.AdminPass)
if r.FirstUser != "" {
fmt.Fprintf(&b, "\nfirst mailbox %s\npassword %s\n", r.FirstUser, r.FirstPass)
}
if r.ConsoleURL != "" {
fmt.Fprintf(&b, "\nconsole %s\n", r.ConsoleURL)
}
if r.WebmailURL != "" {
fmt.Fprintf(&b, "webmail %s\n", r.WebmailURL)
}
return os.WriteFile(filepath.Join(dir, "credentials.txt"), []byte(b.String()), 0o600)
}
func live(ctx context.Context, base string) error {
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, base+"/.well-known/jmap", nil)
if err != nil {
return err
}
resp, err := (&http.Client{}).Do(req)
if err != nil {
return err
}
defer resp.Body.Close()
io.Copy(io.Discard, io.LimitReader(resp.Body, 4096))
// Unauthenticated, so 401 is the healthy answer: something is listening
// and it is a JMAP server rather than a proxy error page.
if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusOK {
return nil
}
return fmt.Errorf("answered %s", resp.Status)
}
func waitFor(ctx context.Context, log Log, what string, limit time.Duration, probe func(context.Context) error) error {
deadline := time.Now().Add(limit)
var last error
for time.Now().Before(deadline) {
if err := probe(ctx); err == nil {
return nil
} else {
last = err
}
select {
case <-ctx.Done():
return ctx.Err()
case <-time.After(2 * time.Second):
}
}
return fmt.Errorf("waited %s for %s: %w", limit, what, last)
}
// serverEnv is what a server on the host reads from its environment: the
// front ends' addresses, and the webmail's client secret whenever there is
// a webmail here in either shape -- without it the server registers no
// client for the webmail, which then answers and signs nobody in.
func serverEnv(o plan.Options, stack compose.Stack, sec compose.Secrets) map[string]string {
env := map[string]string{
"INBUXA_ADMIN_URL": stack.ConsoleURL,
"INBUXA_WEBMAIL_URL": stack.WebmailURL,
}
if stack.WebmailURL != "" {
env["INBUXA_WEBMAIL_CLIENT_SECRET"] = sec.WebmailOAuth
}
if o.Local {
env["INBUXA_PUBLIC_URL"] = stack.ServerPublicURL
}
if stack.CABundle {
env["SSL_CERT_FILE"] = filepath.Join(o.Dir, "ca-bundle.crt")
}
return env
}
// logSource is wherever a server's last lines come from: its container, or
// the journal.
type logSource interface {
Logs(ctx context.Context, service string, lines int) string
}
func withLogs(ctx context.Context, err error, c logSource, service string) error {
logs := c.Logs(ctx, service, 25)
if strings.TrimSpace(logs) == "" {
return err
}
return fmt.Errorf("%w\n\nlast lines from %s:\n%s", err, service, logs)
}
func password(n int) (string, error) {
const alphabet = "abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789"
b := make([]byte, n)
for i := range b {
x, err := rand.Int(rand.Reader, big.NewInt(int64(len(alphabet))))
if err != nil {
return "", err
}
b[i] = alphabet[x.Int64()]
}
return string(b), nil
}
// setupOverride writes a compose override for one step of first boot, and
// returns its path and what removes it. It goes in a new directory only root
// can reach, never at a fixed name in the shared temporary directory, where
// another local user could have put a file or a link of its own first.
func setupOverride(name, content string) (string, func(), error) {
dir, err := os.MkdirTemp("", "inbuxa-setup-")
if err != nil {
return "", nil, err
}
cleanup := func() { os.RemoveAll(dir) }
path := filepath.Join(dir, name)
f, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0o600)
if err == nil {
_, err = f.WriteString(content)
if cerr := f.Close(); err == nil {
err = cerr
}
}
if err != nil {
cleanup()
return "", nil, err
}
return path, cleanup, nil
}
// setupClient is a client for the server at a loopback address, carrying
// the administrator's password or an API key. On the host those are ports
// 8080 and 8081, which any local user may listen on while the installer
// restarts the server: so before each request, whatever listens there must
// be the server the unit started, or nothing is sent. In a container the
// runtime publishes the port and nobody else can take it.
//
// The check is of the client's address at the time of each request, as
// first boot moves its client from 8080 to 8081 once the listeners are
// fitted.
func setupClient(onHost bool, c jmap.Client) *jmap.Client {
cl := &c
if onHost {
cl.Guard = func(ctx context.Context) error { return serversOwnListener(ctx, cl.BaseURL) }
}
return cl
}
// serversOwnListener is nil when what listens on base's port is the host
// server unit's main process.
func serversOwnListener(ctx context.Context, base string) error {
u, err := url.Parse(base)
if err != nil {
return err
}
port, err := strconv.Atoi(u.Port())
if err != nil {
return fmt.Errorf("%s names no port", base)
}
pid := serverMainPID(ctx)
if pid <= 0 {
return fmt.Errorf("%s is not running", HostServerUnit)
}
if err := host.PortHeldBy(port, pid); err != nil {
return fmt.Errorf("%w; the mail server is pid %d, so nothing was sent there", err, pid)
}
return nil
}
// serverMainPID is the host server unit's main process, or 0; a variable so
// a test can stand in for systemd.
var serverMainPID = func(ctx context.Context) int {
out, err := exec.CommandContext(ctx, "systemctl", "show", "-p", "MainPID", "--value", HostServerUnit).Output()
if err != nil {
return 0
}
pid, _ := strconv.Atoi(strings.TrimSpace(string(out)))
return pid
}