install: run again, it keeps the options it isn't given (#84) #85

Merged
jcoffey-dev merged 2 commits from fix/84-install-reuses-record into main 2026-11-18 17:03:01 +00:00
8 changed files with 381 additions and 17 deletions

No files matched your search

+11 -1
View File
@@ -153,11 +153,21 @@ This is early. What is built:
the console's and the webmail's files, the webmail's user, its Node. The
data stays -- the server's volumes or directory, Caddy's certificates, the
credentials and secrets -- with the install record marked removed, so
`install` run again with the same options brings it all back. `--purge`
`install` run again brings it all back. `--purge`
removes the data too, all but `<dir>/backups`, which it names for you to
delete. Docker, and the configuration your own web server loads, are left
alone. To take one component off, run `install` again with it skipped.
- **Running `install` again** -- on a machine with an install recorded,
every option not given on the command line or in `--answers` is the
install's own: its shapes, its proxy, its names, its directory and ACME
settings. So a run changes only what it is given (`install --mail-host
NAME` renames, `install --webmail skip` takes the webmail off, `install
--webmail container` puts it back), and the plan lists what it took from
the install. A component the install doesn't have stays off until it is
asked for. Installs made before 2026.11.18 didn't record the proxy or
the front ends' names; those are read back from the deployment.
- **`certs [--key KEY]`** -- the mail server's own certificate, the one its
mail ports present: who issued it, until when, for which names, whether
it verifies, and where the mail host resolves. Reading it needs nothing.
+137
View File
@@ -0,0 +1,137 @@
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
package main
import (
"fmt"
"path/filepath"
"strings"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/discover"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state"
)
// inherited is one option taken from what is installed rather than from
// the command line, for the plan to say where it came from.
type inherited struct {
Flag, Value string
}
// shapePtrs are where install keeps the three shapes while it parses.
type shapePtrs struct {
server, console, webmail *string
}
// inherit fills every option install was not given (set holds the flags on
// the command line and the keys of an answers file) from the install
// recorded here, so running install again changes only what it is told to
// (#84). Without it an option left out went back to its default: a missing
// `--server host` asked for a move, a missing `--proxy snippets` swapped in
// the managed Caddy. A component the record doesn't list stays skipped.
//
// What installs before 2026.11.18 didn't record (the proxy, the front ends'
// names) is read back from the deployment. Front ends joined to a server
// elsewhere are `inbuxa join`'s, not install's, so they inherit nothing.
func inherit(st *state.State, found discover.Found, set map[string]bool, o *plan.Options, sh shapePtrs) []inherited {
if st == nil || !st.Installed() || st.ServerURL != "" {
return nil
}
var out []inherited
str := func(flag string, dst *string, values ...string) {
if set[flag] {
return
}
for _, v := range values {
if v != "" {
*dst = v
out = append(out, inherited{flag, v})
return
}
}
}
if !set["local"] && st.Local {
o.Local = true
out = append(out, inherited{"local", "true"})
}
str("dir", &o.Dir, st.Dir)
str("domain", &o.Domain, st.Domain)
for _, c := range []struct {
flag string
dst *string
}{{"server", sh.server}, {"console", sh.console}, {"webmail", sh.webmail}} {
if set[c.flag] {
continue
}
v := st.Shapes[c.flag]
if v == "" {
v = string(plan.Skip)
}
*c.dst = v
out = append(out, inherited{c.flag, v})
}
if o.Local {
// Loopback: no names, no proxy, no certificates to carry over.
return out
}
str("mail-host", &o.MailHost, st.MailHost, found.MailHost)
str("console-host", &o.ConsoleHost, st.ConsoleHost, found.ConsoleHost)
str("webmail-host", &o.WebmailHost, st.WebmailHost, found.WebmailHost)
str("proxy", &o.Proxy, st.Proxy, recordedProxy(st, found))
str("email", &o.ACMEEmail, st.ACMEEmail)
str("acme-directory", &o.ACMEDirectory, st.ACMEDirectory)
str("acme-ca-root", &o.ACMECARoot, st.ACMECARoot)
return out
}
// recordedProxy is the proxy an install from before #84 was made with, as
// its files show it: the managed Caddy in the compose file, the nginx files
// --proxy snippets writes, or neither.
func recordedProxy(st *state.State, found discover.Found) string {
switch {
case found.Proxy:
return "caddy"
case st.Dir != "" && fileExists(filepath.Join(st.Dir, "proxy", "nginx-inbuxa.conf")):
return "snippets"
case found.Dir != "":
return "none"
}
return ""
}
// answerKeys are the options an answers file gave, which count as given.
func answerKeys(a answersFile) []string {
var keys []string
add := func(name string, given bool) {
if given {
keys = append(keys, name)
}
}
add("domain", a.Domain != nil)
add("mail-host", a.MailHost != nil)
add("console-host", a.ConsoleHost != nil)
add("webmail-host", a.WebmailHost != nil)
add("email", a.Email != nil)
add("proxy", a.Proxy != nil)
add("dir", a.Dir != nil)
add("local", a.Local != nil)
add("acme-directory", a.ACMEDirectory != nil)
add("acme-ca-root", a.ACMECARoot != nil)
add("server", a.Server != nil)
add("console", a.Console != nil)
add("webmail", a.Webmail != nil)
return keys
}
// inheritedText is the plan's note on what came from the install here.
func inheritedText(from []inherited) string {
var b strings.Builder
b.WriteString("Already installed here, so options not given are the install's own (give one to change it):\n")
for _, i := range from {
fmt.Fprintf(&b, " --%-15s %s\n", i.Flag, i.Value)
}
b.WriteString("\n")
return b.String()
}
+120
View File
@@ -0,0 +1,120 @@
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
package main
import (
"os"
"path/filepath"
"testing"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/discover"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/plan"
"git.coffeylabs.org/inbuxa/inbuxa-installer/internal/state"
)
func shapes() (shapePtrs, *string, *string, *string) {
s, c, w := "container", "container", "container"
return shapePtrs{&s, &c, &w}, &s, &c, &w
}
func recorded() *state.State {
return &state.State{
Dir: "/var/lib/inbuxa", Domain: "example.com", MailHost: "mail.example.com",
Shapes: map[string]string{"server": "host", "console": "container"},
Proxy: "snippets", ConsoleHost: "admin.example.com", WebmailHost: "webmail.example.com",
ACMEEmail: "[email protected]",
}
}
// #84: a re-run with only new names keeps every other option it was installed with.
func TestInheritKeepsWhatWasNotGiven(t *testing.T) {
var o plan.Options
sh, server, console, webmail := shapes()
o.MailHost = "mail.example.net"
from := inherit(recorded(), discover.Found{}, map[string]bool{"mail-host": true}, &o, sh)
if *server != "host" || *console != "container" || *webmail != "skip" {
t.Fatalf("shapes = %s/%s/%s, want host/container/skip", *server, *console, *webmail)
}
if o.Proxy != "snippets" || o.Domain != "example.com" || o.ConsoleHost != "admin.example.com" {
t.Fatalf("options = %+v", o)
}
if o.MailHost != "mail.example.net" {
t.Fatalf("a given flag was overridden: mail-host %q", o.MailHost)
}
for _, i := range from {
if i.Flag == "mail-host" {
t.Fatal("mail-host was given, so it isn't inherited")
}
}
}
func TestInheritLeavesGivenShapesAlone(t *testing.T) {
var o plan.Options
sh, server, _, webmail := shapes()
*server = "container"
*webmail = "host"
inherit(recorded(), discover.Found{}, map[string]bool{"server": true, "webmail": true}, &o, sh)
if *server != "container" || *webmail != "host" {
t.Fatalf("given shapes changed: %s %s", *server, *webmail)
}
}
func TestInheritNothingOnAFreshOrJoinedMachine(t *testing.T) {
var o plan.Options
sh, server, _, _ := shapes()
if from := inherit(&state.State{Shapes: map[string]string{}}, discover.Found{}, nil, &o, sh); from != nil {
t.Fatalf("fresh machine inherited %v", from)
}
joined := &state.State{ServerURL: "https://mail.example.com", Shapes: map[string]string{"console": "container"}}
if from := inherit(joined, discover.Found{}, nil, &o, sh); from != nil || *server != "container" {
t.Fatalf("joined front ends inherited %v", from)
}
}
// An install from before #84 has no proxy or front-end names in its record.
func TestInheritReadsOlderInstallsFromTheMachine(t *testing.T) {
dir := t.TempDir()
if err := os.MkdirAll(filepath.Join(dir, "proxy"), 0o755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "proxy", "nginx-inbuxa.conf"), nil, 0o644); err != nil {
t.Fatal(err)
}
st := &state.State{Dir: dir, Domain: "example.com", Shapes: map[string]string{"server": "container"}}
found := discover.Found{Dir: dir, MailHost: "mx.example.com", ConsoleHost: "console.example.org"}
var o plan.Options
sh, _, _, _ := shapes()
inherit(st, found, nil, &o, sh)
if o.Proxy != "snippets" || o.MailHost != "mx.example.com" || o.ConsoleHost != "console.example.org" {
t.Fatalf("options = %+v", o)
}
if got := recordedProxy(&state.State{}, discover.Found{Dir: dir, Proxy: true}); got != "caddy" {
t.Fatalf("compose with caddy: %q", got)
}
}
func TestInheritLocalCarriesNoNames(t *testing.T) {
st := &state.State{Dir: "/var/lib/inbuxa", Domain: "example.test", Local: true, Shapes: map[string]string{"server": "container"}}
var o plan.Options
sh, _, _, _ := shapes()
inherit(st, discover.Found{MailHost: "mail.example.test"}, nil, &o, sh)
if !o.Local || o.MailHost != "" || o.Proxy != "" {
t.Fatalf("options = %+v", o)
}
}
func TestAnswerKeysCountAsGiven(t *testing.T) {
a, err := parseAnswers([]byte(`{"proxy":"caddy","server":"host"}`))
if err != nil {
t.Fatal(err)
}
set := map[string]bool{}
for _, k := range answerKeys(a) {
set[k] = true
}
if !set["proxy"] || !set["server"] || set["domain"] {
t.Fatalf("set = %v", set)
}
}
+16 -4
View File
@@ -88,7 +88,7 @@ const usage = `inbuxa -- install the inbuxa suite on this machine
inbuxa man the manual page, in roff (inbuxa man > inbuxa.1)
inbuxa version this program's version
install flags:
install flags (run again where it is installed, any not given are the install's own):
--domain NAME the mail domain (required unless --local)
--mail-host NAME default: mail.DOMAIN
--console-host NAME default: admin.DOMAIN
@@ -352,9 +352,9 @@ func install(args []string) int {
if err := fs.Parse(args); err != nil {
return 2
}
set := map[string]bool{}
fs.Visit(func(fl *flag.Flag) { set[fl.Name] = true })
if *answers != "" {
set := map[string]bool{}
fs.Visit(func(fl *flag.Flag) { set[fl.Name] = true })
b, err := os.ReadFile(*answers)
if err != nil {
fmt.Fprintln(os.Stderr, "reading --answers: "+err.Error())
@@ -366,6 +366,16 @@ func install(args []string) int {
return 2
}
applyAnswers(a, set, &o, server, console, webmail)
for _, k := range answerKeys(a) {
set[k] = true
}
}
f := host.Survey(context.Background())
// Running it again on an installed machine changes only what it is given (#84).
var from []inherited
if st, err := state.Load(); err == nil && st.Installed() {
found := discover.Run(context.Background(), f, st.Dir)
from = inherit(st, found, set, &o, shapePtrs{server, console, webmail})
}
for _, c := range []struct {
comp plan.Component
@@ -379,13 +389,15 @@ func install(args []string) int {
o.Choices = append(o.Choices, plan.Choice{Component: c.comp, Shape: s})
}
f := host.Survey(context.Background())
p, err := plan.Build(f, o)
if err != nil {
fmt.Fprintln(os.Stderr, "cannot install as asked: "+err.Error())
fmt.Fprint(os.Stderr, "\n"+render(f))
return 1
}
if len(from) > 0 {
fmt.Print(inheritedText(from))
}
fmt.Print(p.String())
moving := false
if st, err := state.Load(); err == nil {
+27
View File
@@ -17,6 +17,7 @@
package apply
import (
"bytes"
"context"
"crypto/rand"
"fmt"
@@ -232,15 +233,21 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
log.Step("writing the deployment into %s", dir)
var sec compose.Secrets
var err error
caddyChanged := false
if stack.Empty() {
if sec, err = compose.EnsureSecrets(dir); err != nil {
return nil, err
}
log.Info(".env (nothing runs in containers here)")
} else {
// Caddy reads its file at start only, and a rewritten bind-mounted
// file doesn't make compose recreate it: what changed is reloaded below.
before, _ := os.ReadFile(filepath.Join(dir, "Caddyfile"))
if sec, err = compose.Write(dir, &stack); err != nil {
return nil, err
}
after, _ := os.ReadFile(filepath.Join(dir, "Caddyfile"))
caddyChanged = stack.Proxy && len(before) > 0 && !bytes.Equal(before, after)
log.Info("compose.yaml, .env%s", map[bool]string{true: " and Caddyfile", false: ""}[stack.Proxy])
}
@@ -337,6 +344,17 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
log.Info("your web server still terminates TLS for the server's names: run this again with --key to pass them through to it instead (#48)")
}
res, err := converge(ctx, o, stack, cmp, hs, serverChanged, existing, f, log)
if err == nil && caddyChanged {
// New names, or a front end added or taken off: without this
// Caddy kept serving, and certifying, the old ones.
log.Step("reloading the proxy for its new configuration")
if rerr := cmp.Run(ctx, "exec", "-T", "caddy", "caddy", "reload", "--config", "/etc/caddy/Caddyfile", "--adapter", "caddyfile"); rerr != nil {
log.Info("caddy reload didn't take (%v); restarting it", rerr)
if rerr := cmp.Run(ctx, "restart", "caddy"); rerr != nil {
return res, fmt.Errorf("restarting the proxy for its new configuration: %w", rerr)
}
}
}
// An install from before #70 has no log files; a run with a key
// gives it them, and after a move points them at this shape's
// directory.
@@ -671,6 +689,7 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
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
recordOptions(st, o)
st.PassThrough = stack.PassThrough
st.LogFiles = logFiles
st.Shapes = map[string]string{}
@@ -864,9 +883,17 @@ func convergeHost(ctx context.Context, o plan.Options, stack compose.Stack, cmp
return res, nil
}
// recordOptions writes down the options the state has no other field for,
// so a later install starts from them (#84).
func recordOptions(st *state.State, o plan.Options) {
st.Proxy, st.ConsoleHost, st.WebmailHost = o.Proxy, o.ConsoleHost, o.WebmailHost
st.ACMEEmail, st.ACMEDirectory, st.ACMECARoot = o.ACMEEmail, o.ACMEDirectory, o.ACMECARoot
}
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
recordOptions(st, o)
st.Installer = "server " + release.ServerVersion
st.RemovedAt = nil // installed again, on what was kept
st.Shapes = map[string]string{}
+29
View File
@@ -31,6 +31,8 @@ type Found struct {
Dir string // the deployment directory, when there is one
Domain string // read back from the deployment
MailHost string //
ConsoleHost string // the console's name, from the address the server is given for it
WebmailHost string // the webmail's, the same way
Services map[string]string // component -> running|stopped|absent
Compose []string // services the compose file declares
Runtime string // what is running them
@@ -71,6 +73,26 @@ var Dirs = []string{"/var/lib/inbuxa", "/opt/inbuxa"}
var serviceLine = regexp.MustCompile(`(?m)^ ([a-z][a-z0-9_-]*):\s*$`)
var hostnameLine = regexp.MustCompile(`(?m)^\s+hostname:\s*(\S+)\s*$`)
// The front ends' addresses, as the server is given them: a key in the
// compose file's environment, or a line in server.env for a server on the host.
var (
adminURLLine = regexp.MustCompile(`(?m)^\s*INBUXA_ADMIN_URL\s*[:=]\s*"?https://([^\s/":]+)`)
webmailURLLine = regexp.MustCompile(`(?m)^\s*INBUXA_WEBMAIL_URL\s*[:=]\s*"?https://([^\s/":]+)`)
)
// FrontEndHosts reads the console's and the webmail's names out of a
// compose file or server.env. Plain-HTTP addresses (a --local install) give
// nothing: they are loopback binds, not names.
func FrontEndHosts(text string) (console, webmail string) {
if m := adminURLLine.FindStringSubmatch(text); m != nil {
console = m[1]
}
if m := webmailURLLine.FindStringSubmatch(text); m != nil {
webmail = m[1]
}
return console, webmail
}
// Run looks for a deployment and reports what it finds. It never changes
// anything, and a machine with nothing on it is not an error.
func Run(ctx context.Context, f host.Facts, dirs ...string) Found {
@@ -107,12 +129,19 @@ func Run(ctx context.Context, f host.Facts, dirs ...string) Found {
found.Services["console"] = "running"
}
if b, err := os.ReadFile(filepath.Join(found.Dir, "server.env")); err == nil {
found.ConsoleHost, found.WebmailHost = FrontEndHosts(string(b))
}
b, err := os.ReadFile(filepath.Join(found.Dir, "compose.yaml"))
if err != nil {
// A server on the host with nothing beside it has no compose file.
return found
}
text := string(b)
if c, w := FrontEndHosts(text); c != "" || w != "" {
found.ConsoleHost, found.WebmailHost = c, w
}
for _, m := range serviceLine.FindAllStringSubmatch(text, -1) {
name := m[1]
if name == "caddy" {
+20
View File
@@ -0,0 +1,20 @@
// SPDX-FileCopyrightText: 2026 Coffey Labs LLC
// SPDX-License-Identifier: AGPL-3.0-or-later
package discover
import "testing"
func TestFrontEndHosts(t *testing.T) {
compose := "services:\n server:\n environment:\n INBUXA_ADMIN_URL: https://admin.example.com\n INBUXA_WEBMAIL_URL: https://webmail.example.com\n"
if c, w := FrontEndHosts(compose); c != "admin.example.com" || w != "webmail.example.com" {
t.Fatalf("compose: %q %q", c, w)
}
env := "INBUXA_ADMIN_URL=\"https://console.example.org\"\nINBUXA_WEBMAIL_URL=\n"
if c, w := FrontEndHosts(env); c != "console.example.org" || w != "" {
t.Fatalf("server.env: %q %q", c, w)
}
if c, _ := FrontEndHosts("INBUXA_ADMIN_URL=http://127.0.0.1:8082\n"); c != "" {
t.Fatalf("a loopback bind is not a name: %q", c)
}
}
+21 -12
View File
@@ -25,18 +25,27 @@ const Path = "/etc/inbuxa/install.json"
// State is the file.
type State struct {
Version int `json:"version"`
Machine string `json:"machine"` // its name in the topology
Dir string `json:"dir"` // the deployment directory
Runtime string `json:"runtime,omitempty"` // docker or podman
Domain string `json:"domain,omitempty"` //
MailHost string `json:"mailHost,omitempty"` // the server's name; installs before 2026.10.13 did not record it
Local bool `json:"local,omitempty"` // --local: loopback only, no certificates
Shapes map[string]string `json:"shapes"` // component -> container|host
Topology string `json:"topology,omitempty"` // the file this came from, if any
ServerURL string `json:"serverUrl,omitempty"` // the server on another machine these front ends were joined to
Updated time.Time `json:"updated"` //
Installer string `json:"installer,omitempty"` // the version that wrote this
Version int `json:"version"`
Machine string `json:"machine"` // its name in the topology
Dir string `json:"dir"` // the deployment directory
Runtime string `json:"runtime,omitempty"` // docker or podman
Domain string `json:"domain,omitempty"` //
MailHost string `json:"mailHost,omitempty"` // the server's name; installs before 2026.10.13 did not record it
Local bool `json:"local,omitempty"` // --local: loopback only, no certificates
Shapes map[string]string `json:"shapes"` // component -> container|host
// The rest of the install's options, so running install again changes
// only what it is given (#84). Installs before 2026.11.18 did not record
// them; install reads them back from the machine instead.
Proxy string `json:"proxy,omitempty"` // caddy | snippets | none
ConsoleHost string `json:"consoleHost,omitempty"` //
WebmailHost string `json:"webmailHost,omitempty"` //
ACMEEmail string `json:"acmeEmail,omitempty"` //
ACMEDirectory string `json:"acmeDirectory,omitempty"` // a private ACME CA, when one was given
ACMECARoot string `json:"acmeCaRoot,omitempty"` // that CA's root
Topology string `json:"topology,omitempty"` // the file this came from, if any
ServerURL string `json:"serverUrl,omitempty"` // the server on another machine these front ends were joined to
Updated time.Time `json:"updated"` //
Installer string `json:"installer,omitempty"` // the version that wrote this
// PassThrough is whether the server's HTTPS listener was fitted to the
// name router --proxy snippets writes for nginx (#48). Installs from