`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.
315 lines
11 KiB
Go
315 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("host installs of the console and the webmail are not built yet: %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
|
|
})
|
|
}
|
|
problems := Verify(ctx, res, false, console, webmail, 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)
|
|
}
|