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

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

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

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

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

319 lines
11 KiB
Go

// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
package apply
// Join installs the console and the webmail on this machine, for a mail server
// that already runs on another one.
//
// The other machine is never reached except as a browser or a mail client
// would reach it: over its own HTTPS, with an API key its administrator made
// in the console. Through that key the front ends' addresses go into the
// server's inbuxa:FrontEnds, which registers their OAuth clients and puts
// their origins on the cross-origin allowlist, on every node, with no
// restart. Nothing is copied between the machines but that key, and the
// webmail's client secret, which is made here and leaves only inside that
// one request.
import (
"context"
"errors"
"fmt"
"net"
"net/http"
"os"
"path/filepath"
"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/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/state"
)
// JoinCheck is what the server says before anything is installed: that the
// key works, that the server can take front ends this way, and that nothing
// it already lists would be replaced unasked. It changes nothing, so a dry
// run makes it too.
func JoinCheck(ctx context.Context, o plan.Options, key string) error {
srv := &jmap.Client{BaseURL: o.ServerURL, Token: key}
accountID, err := srv.AccountID(ctx)
if err != nil {
var he *jmap.HTTPError
if errors.As(err, &he) && he.Status == http.StatusUnauthorized {
return fmt.Errorf("the server refused the API key; make one in the console under your account's API keys, then pass it with --key")
}
return fmt.Errorf("reaching %s: %w", o.ServerURL, err)
}
fe, err := srv.GetFrontEnds(ctx, accountID)
if err != nil {
return err
}
consoleURL, webmailURL := joinURLs(o)
if o.Shape(plan.Console) != plan.Skip && fe.AdminURL != nil && *fe.AdminURL != consoleURL && !o.Replace {
return fmt.Errorf("the server already lists a console at %s; pass --replace to put this one (%s) in its place", *fe.AdminURL, consoleURL)
}
if o.Shape(plan.Webmail) != plan.Skip {
if fe.EnvironmentWebmailClientSecret {
return fmt.Errorf("the server takes its webmail's client secret from INBUXA_WEBMAIL_CLIENT_SECRET in its environment, " +
"so a webmail elsewhere can't be given one; remove that variable on the server, or join with --webmail skip")
}
if fe.WebmailURL != nil && *fe.WebmailURL != webmailURL && !o.Replace {
return fmt.Errorf("the server already lists a webmail at %s; pass --replace to put this one (%s) in its place", *fe.WebmailURL, webmailURL)
}
}
return nil
}
// joinURLs are the addresses the front ends here will be reached at.
func joinURLs(o plan.Options) (console, webmail string) {
if o.Local {
return "http://127.0.0.1:8082", "http://127.0.0.1:8080"
}
return "https://" + o.ConsoleHost, "https://" + o.WebmailHost
}
// Join carries out a join plan.
func Join(ctx context.Context, p plan.Plan, f host.Facts, key string, log Log) (*Result, error) {
o := p.Options
if o.ServerURL == "" {
return nil, errors.New("join needs the server's address")
}
if o.Shape(plan.Server) != plan.Skip {
return nil, errors.New("join installs front ends for a server elsewhere; the server itself is installed with install")
}
for _, c := range []plan.Component{plan.Console, plan.Webmail} {
if o.Shape(c) == plan.Host {
return nil, fmt.Errorf("join installs the console and the webmail in containers for now: %s was asked for as a host install", c)
}
}
if o.Shape(plan.Console) == plan.Skip && o.Shape(plan.Webmail) == plan.Skip {
return nil, errors.New("nothing to join: both the console and the webmail are skipped")
}
if st, err := state.Load(); err == nil && st.Shapes["server"] != "" {
return nil, fmt.Errorf("this machine runs the mail server itself (a %s install); its front ends are added with install, not join", st.Shapes["server"])
}
log.Step("asking the server at %s", o.ServerURL)
if err := JoinCheck(ctx, o, key); err != nil {
return nil, err
}
srv := &jmap.Client{BaseURL: o.ServerURL, Token: key}
accountID, err := srv.AccountID(ctx)
if err != nil {
return nil, err
}
log.Info("the key works, and the server takes front ends over JMAP")
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
}
f = host.Survey(ctx)
}
if !f.Runtime.Usable {
return nil, fmt.Errorf("the front ends run in containers, and containers are not usable here: %s", f.Runtime.Why)
}
consoleURL, webmailURL := joinURLs(o)
stack := compose.Stack{
Version: "dev",
Project: "inbuxa",
Domain: o.Domain,
Email: o.ACMEEmail,
Local: o.Local,
ConsoleHost: o.ConsoleHost,
WebmailHost: o.WebmailHost,
Console: o.Shape(plan.Console) == plan.Container,
Webmail: o.Shape(plan.Webmail) == plan.Container,
Proxy: !o.Local && o.Proxy == "caddy",
RemoteServerURL: o.ServerURL,
ServerPublicURL: o.ServerURL,
ConsoleImage: DefaultConsoleImage,
WebmailImage: DefaultWebmailImage,
CaddyImage: DefaultCaddyImage,
ConsoleBind: "127.0.0.1:8082",
WebmailBind: "127.0.0.1:8080",
Subnet: DefaultSubnet,
ACMEDirectory: o.ACMEDirectory,
}
if stack.Console {
stack.ConsoleURL = consoleURL
}
if stack.Webmail {
stack.WebmailURL = webmailURL
}
if o.ACMECARoot != "" {
if err := copyACMERoot(o.ACMECARoot, o.Dir); err != nil {
return nil, err
}
stack.ACMECARoot = "acme-ca-root.pem"
}
log.Step("writing the deployment into %s", o.Dir)
sec, err := compose.Write(o.Dir, &stack)
if err != nil {
return nil, err
}
log.Info("compose.yaml, .env%s", map[bool]string{true: " and Caddyfile", false: ""}[stack.Proxy])
docker.UseRuntime(f.Runtime)
cmp := docker.Compose{Dir: o.Dir, Runtime: f.Runtime}
log.Step("fetching the images")
if err := cmp.Run(ctx, "pull", "--quiet"); err != nil {
return nil, err
}
log.Step("registering these front ends with the server")
update := map[string]any{}
if stack.Console {
update["adminUrl"] = consoleURL
}
if stack.Webmail {
update["webmailUrl"] = webmailURL
update["webmailClientSecret"] = sec.WebmailOAuth
}
if err := srv.SetFrontEnds(ctx, accountID, update); err != nil {
return nil, fmt.Errorf("inbuxa:FrontEnds: %w", err)
}
for k, v := range update {
if k != "webmailClientSecret" {
log.Info("%s %v", k, v)
}
}
// Every webmail request reaches the server from one address, this
// machine's, and the server bans per address: exempted, a scanner
// probing the webmail can't take everybody's webmail with it.
if stack.Webmail {
addresses := joinExemptAddresses(ctx, o, stack)
if len(addresses) == 0 {
log.Info("could not tell which address the server sees the webmail at; exempt it with --exempt-address, or in the console under the auto-ban's allowed addresses")
}
for _, addr := range addresses {
err := srv.AllowIP(ctx, addr, "the webmail at "+webmailURL+": every request arrives from this address")
switch {
case err == nil:
log.Info("exempted %s from the auto-ban; the server applies it at its next restart", addr)
case strings.Contains(err.Error(), "primaryKeyViolation"):
// Exempted already: by an earlier join, or by hand
log.Info("%s is already exempted from the auto-ban", addr)
default:
return nil, fmt.Errorf("exempting %s from the auto-ban: %w", addr, err)
}
}
}
log.Step("starting the front ends")
if err := cmp.Run(ctx, "up", "-d", "--remove-orphans"); err != nil {
return nil, err
}
st, err := state.Load()
if err == nil {
st.ServerURL = o.ServerURL
saveState(st, o, f, log)
}
return &Result{
Dir: o.Dir,
ConsoleURL: stack.ConsoleURL,
WebmailURL: stack.WebmailURL,
ServerURL: o.ServerURL,
}, nil
}
// joinExemptAddresses is where the server sees the webmail's requests come
// from: what the operator said, loopback for a server on this machine's own
// loopback, or else what the webmail's name resolves to -- the address its
// DNS points at this machine, which is the one it sends from unless
// something in between rewrites it.
func joinExemptAddresses(ctx context.Context, o plan.Options, stack compose.Stack) []string {
if o.ExemptAddress != "" {
return []string{o.ExemptAddress}
}
if stack.WebmailOnHost() {
return []string{"127.0.0.1"}
}
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
addrs, err := net.DefaultResolver.LookupHost(ctx, o.WebmailHost)
if err != nil {
return nil
}
return addrs
}
// JoinVerify is join's last step: the front ends answer here, and the server
// lets the console call it from the browser, which is the part only the
// server can say.
func JoinVerify(ctx context.Context, res *Result, console, webmail bool, log Log) []string {
// Started a moment ago: give them the time to answer at all before
// asking whether they answer correctly.
for _, c := range []struct {
want bool
what string
url string
}{{console, "the console", "http://127.0.0.1:8082/"}, {webmail, "the webmail", "http://127.0.0.1:8080/api/health"}} {
if !c.want {
continue
}
_ = waitFor(ctx, log, c.what+" to start", 60*time.Second, func(ctx context.Context) error {
req, _ := http.NewRequestWithContext(ctx, http.MethodGet, c.url, nil)
resp, err := (&http.Client{Timeout: 5 * time.Second}).Do(req)
if err != nil {
return err
}
resp.Body.Close()
if resp.StatusCode >= 500 {
return fmt.Errorf("answered %s", resp.Status)
}
return nil
})
}
o := plan.Options{Dir: res.Dir, Choices: []plan.Choice{
{Component: plan.Console, Shape: map[bool]plan.Shape{true: plan.Container, false: plan.Skip}[console]},
{Component: plan.Webmail, Shape: map[bool]plan.Shape{true: plan.Container, false: plan.Skip}[webmail]},
}}
problems := Verify(ctx, res, o, false, log)
if console {
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, http.MethodOptions, res.ServerURL+"/jmap/session", nil)
origin := strings.TrimRight(res.ConsoleURL, "/")
req.Header.Set("Origin", origin)
req.Header.Set("Access-Control-Request-Method", "GET")
req.Header.Set("Access-Control-Request-Headers", "authorization")
resp, err := (&http.Client{}).Do(req)
switch {
case err != nil:
problems = append(problems, fmt.Sprintf("the server did not answer at %s: %v", res.ServerURL, err))
case resp.Header.Get("Access-Control-Allow-Origin") != origin:
resp.Body.Close()
problems = append(problems, fmt.Sprintf("the server does not let the console at %s call it yet (no Access-Control-Allow-Origin)", origin))
default:
resp.Body.Close()
log.Info("the server lets the console call it")
}
}
return problems
}
// copyACMERoot puts a private ACME CA's root beside the deployment, for
// Caddy: the only thing here that asks for certificates.
func copyACMERoot(path, dir string) error {
root, err := os.ReadFile(path)
if err != nil {
return fmt.Errorf("reading the ACME CA root: %w", err)
}
if err := os.MkdirAll(dir, 0o750); err != nil {
return err
}
return os.WriteFile(filepath.Join(dir, "acme-ca-root.pem"), root, 0o644)
}