--proxy snippets writes what it promised: nginx and Caddy configuration #19

Merged
jcoffey-dev merged 1 commits from feat/proxy-snippets into main 2026-10-12 16:52:53 +00:00
10 changed files with 409 additions and 11 deletions

No files matched your search

+11 -3
View File
@@ -46,6 +46,14 @@ This is early. What is built:
it is not a second installer -- and it is built on the standard library
alone, like the rest. Without a terminal it says which flags to use.
- **`--proxy snippets`** -- for a machine that already runs nginx or Caddy:
nothing here takes 80 or 443, and the installer writes
`<dir>/proxy/nginx-inbuxa.conf` and `<dir>/proxy/Caddyfile.fragment` for
that web server to load, trusts it in front of the suite (its
X-Forwarded-For, and an exemption from the auto-ban), and leaves loading
and reloading to you. Once it is loaded, the mail server's own
certificates are turned on in the console. `--proxy none` writes nothing.
- **`survey`** -- the machine's facts: distribution, init, whether Docker is
usable *by this user*, Node's version, which of the suite's ports are free
and what holds the ones that are not, memory, disk, and whether an install
@@ -100,9 +108,8 @@ This is early. What is built:
asked in a script whether it still matches itself.
Not built yet: host installs of the console and the webmail, `join` in the
interface (it is a command for now), `upgrade`, `uninstall`, moving the
server between a container and the host, and `--proxy snippets`, which the
plan describes but nothing writes yet. The design is in the inbuxa specification (§6.1 and
interface (it is a command for now), `upgrade`, `uninstall`, and moving the
server between a container and the host. The design is in the inbuxa specification (§6.1 and
the installer draft); the phases are there too.
inbuxa install --local --domain example.test --install-deps --yes
@@ -144,6 +151,7 @@ is tested on a throwaway virtual machine rather than on anybody's desk:
e2e/vm/run.sh e2e/cases/install-host.sh the server on the host, the rest beside it
e2e/vm/run.sh e2e/cases/join.sh front ends joined to a server elsewhere
e2e/vm/run.sh e2e/cases/interface.sh the interface, driven key by key in a terminal
e2e/vm/run.sh e2e/cases/proxy-snippets.sh behind nginx, from the configuration it writes
e2e/vm/run.sh e2e/cases/topology.sh growing and shrinking from a file
e2e/vm/run.sh e2e/cases/status-export.sh intent against reality, and the file
OLD_REF=<commit> e2e/vm/run.sh e2e/cases/upgrade-volumes.sh
+3
View File
@@ -226,6 +226,9 @@ func install(args []string) int {
if res.ZoneFile != "" {
fmt.Printf(" dns records %s\n", res.ZoneFile)
}
if res.ProxyConfig != "" {
fmt.Printf(" proxy config %s (load it into your web server)\n", res.ProxyConfig)
}
if len(problems) > 0 {
return 1
}
+74
View File
@@ -0,0 +1,74 @@
#!/bin/bash
# SPDX-FileCopyrightText: 2026 Coffey Labs LLC
# SPDX-License-Identifier: AGPL-3.0-or-later
#
# --proxy snippets on a machine that already runs nginx: the installer takes
# neither 80 nor 443, writes the configuration for nginx, and the suite is
# then reached through nginx on its real names once that file is loaded --
# certificates being the operator's, self-signed here.
#
# Run from the host with: e2e/vm/run.sh e2e/cases/proxy-snippets.sh
set -uo pipefail
pass=0; fail=0
ok() { echo " ok $*"; pass=$((pass+1)); }
bad() { echo " FAIL $*"; fail=$((fail+1)); }
DIR=/var/lib/inbuxa
D=example.test
echo "==> a machine with nginx already on it"
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq nginx openssl >/dev/null 2>&1
systemctl is-active --quiet nginx && ok "nginx is running, holding 80" || { bad "no nginx"; echo "==> $pass passed, $fail failed"; exit 1; }
echo
echo "==> install behind it"
OUT="$(/tmp/inbuxa install --domain $D --proxy snippets --install-deps --yes 2>&1)"; rc=$?
echo "$OUT" | grep -v '^ |' | tail -14 | sed 's/^/ /'
[ $rc -eq 0 ] && ok "installed (exit 0)" || bad "exit $rc"
grep -q "proxy config.*$DIR/proxy" <<<"$OUT" && ok "the summary names the proxy configuration" || bad "no proxy config in the summary"
[ -f $DIR/proxy/nginx-inbuxa.conf ] && [ -f $DIR/proxy/Caddyfile.fragment ] && ok "nginx-inbuxa.conf and Caddyfile.fragment written" || bad "the configuration files are missing"
grep -q "caddy" $DIR/compose.yaml && bad "a Caddy was put here anyway" || ok "no Caddy of its own"
systemctl is-active --quiet nginx && ok "nginx was left running, untouched" || bad "nginx is not running any more"
echo
echo "==> load it, as the operator would"
mkdir -p /etc/ssl/inbuxa
for n in mail.$D admin.$D webmail.$D; do
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -days 2 -subj "/CN=$n" \
-addext "subjectAltName=DNS:$n,DNS:autoconfig.$D,DNS:autodiscover.$D,DNS:mta-sts.$D,DNS:ua-auto-config.$D" \
-keyout /etc/ssl/inbuxa/$n.key.pem -out /etc/ssl/inbuxa/$n.fullchain.pem 2>/dev/null
done
cp $DIR/proxy/nginx-inbuxa.conf /etc/nginx/conf.d/inbuxa.conf
OUT="$(nginx -t 2>&1)" && ok "nginx -t accepts it" || { bad "nginx -t"; echo "$OUT" | sed 's/^/ /'; }
systemctl reload nginx
# A reload returns before nginx's old workers have finished; until they
# have, port 80 can still be answered from the configuration before it.
sleep 3
echo
echo "==> the suite, through nginx"
via() { curl -sk --resolve "$1:443:127.0.0.1" --resolve "$1:80:127.0.0.1" "${@:2}"; }
CODE=$(via mail.$D -o /dev/null -w '%{http_code}' https://mail.$D/.well-known/jmap)
case "$CODE" in 30*|200|401) ok "the mail server answers on https://mail.$D ($CODE)" ;; *) bad "https://mail.$D/.well-known/jmap answered $CODE" ;; esac
via admin.$D https://admin.$D/ | grep -q "content=\"https://mail.$D\"" && ok "the console, pointed at https://mail.$D" || bad "the console is not served through nginx"
via webmail.$D https://webmail.$D/api/health | grep -q '"ok":true' && ok "the webmail is healthy through nginx" || bad "the webmail is not healthy through nginx"
# The mail server's own 404 is a JSON problem document; nginx's is a page.
BODY=$(via mail.$D http://mail.$D/.well-known/acme-challenge/probe)
grep -q "<html" <<<"$BODY" && { bad "port 80 answered the challenge path itself, not the mail server"; echo "$BODY" | head -5 | sed 's/^/ /'; } || ok "port 80 passes the server's challenges to it"
CODE=$(via admin.$D -o /dev/null -w '%{http_code}' http://admin.$D/)
if [ "$CODE" = 308 ]; then ok "port 80 redirects the console to https"; else
bad "http://admin.$D answered $CODE"
via admin.$D -sv http://admin.$D/ 2>&1 | grep -E "^[<>] |^\* Connected" | head -12 | sed 's/^/ /'
nginx -T 2>/dev/null | grep -n -E "^# configuration file|listen|server_name" | head -40 | sed 's/^/ /'
fi
echo
echo "==> again: converges, and rewrites the file for what is here"
rm $DIR/proxy/nginx-inbuxa.conf
OUT="$(/tmp/inbuxa install --domain $D --proxy snippets --yes 2>&1)"; rc=$?
[ $rc -eq 0 ] && [ -f $DIR/proxy/nginx-inbuxa.conf ] && ok "a second run converges and writes it again" || { bad "second run exit $rc"; echo "$OUT" | tail -6 | sed 's/^/ /'; }
echo
echo "==> $pass passed, $fail failed"
[ "$fail" -eq 0 ]
+46 -3
View File
@@ -60,6 +60,7 @@ type Result struct {
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
@@ -250,7 +251,15 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
// 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() {
return converge(ctx, o, stack, cmp, hs, existing, f, log)
res, err := converge(ctx, o, stack, cmp, hs, existing, f, log)
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,
@@ -430,7 +439,32 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
}
}
}
if stack.Webmail || stack.Proxy {
// 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") }
@@ -452,7 +486,16 @@ func Run(ctx context.Context, p plan.Plan, f host.Facts, log Log) (*Result, erro
// 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 !o.Local && !stack.Proxy {
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(), ", "))
}
+38
View File
@@ -66,6 +66,7 @@ type Stack struct {
WebmailBind string
Subnet string
GatewayIP string // the project network's gateway: where the host is, seen from inside it
ServerIP string
ConsoleIP string
WebmailIP string
@@ -82,6 +83,10 @@ type Stack struct {
ACMEDirectory string
ACMECARoot string
CABundle bool
// Dir is the deployment directory, which the proxy configuration for
// the operator's own web server names.
Dir string
}
// ServerNames is every name the server's certificate and the proxy need:
@@ -120,6 +125,7 @@ func (s *Stack) Addresses() error {
}
return a.String()
}
s.GatewayIP = at(1)
s.ServerIP, s.ConsoleIP, s.WebmailIP, s.CaddyIP = at(10), at(11), at(12), at(13)
if s.ServerIP == "" || s.CaddyIP == "" {
return fmt.Errorf("subnet %q is too small for the stack", s.Subnet)
@@ -298,3 +304,35 @@ func secret() (string, error) {
}
return base64.RawURLEncoding.EncodeToString(b), nil
}
// ProxySnippets are the files --proxy snippets writes, for the web server the
// operator already runs: an nginx configuration and a Caddyfile fragment.
var ProxySnippets = map[string]string{
"nginx-inbuxa.conf.tmpl": "nginx-inbuxa.conf",
"Caddyfile.fragment.tmpl": "Caddyfile.fragment",
}
// WriteProxySnippets writes them into dir/proxy and returns that directory.
// Nothing is loaded or reloaded: that web server is the operator's.
func WriteProxySnippets(dir string, s Stack) (string, error) {
out := filepath.Join(dir, "proxy")
if err := os.MkdirAll(out, 0o755); err != nil {
return "", err
}
s.Dir = dir
funcs := template.FuncMap{"join": strings.Join}
for name, file := range ProxySnippets {
t, err := template.New(name).Funcs(funcs).ParseFS(templates, "templates/"+name)
if err != nil {
return "", err
}
var b strings.Builder
if err := t.Execute(&b, s); err != nil {
return "", fmt.Errorf("%s: %w", name, err)
}
if err := os.WriteFile(filepath.Join(out, file), []byte(b.String()), 0o644); err != nil {
return "", err
}
}
return out, nil
}
+52
View File
@@ -119,3 +119,55 @@ func TestJoinedToALoopbackServerTheWebmailSharesTheHost(t *testing.T) {
t.Errorf("the webmail would be exempted at %s", s.WebmailIP)
}
}
func TestProxySnippetsPointAtLoopback(t *testing.T) {
dir := t.TempDir()
s := stack(false)
if err := s.Addresses(); err != nil {
t.Fatal(err)
}
out, err := WriteProxySnippets(dir, *s)
if err != nil {
t.Fatal(err)
}
nginx, _ := os.ReadFile(filepath.Join(out, "nginx-inbuxa.conf"))
caddy, _ := os.ReadFile(filepath.Join(out, "Caddyfile.fragment"))
for _, want := range []string{
"server_name mail.example.com autoconfig.example.com",
"proxy_pass http://127.0.0.1:8081;", "proxy_pass http://127.0.0.1:8082;", "proxy_pass http://127.0.0.1:8080;",
"location /.well-known/acme-challenge/",
"proxy_set_header X-Forwarded-For $remote_addr;",
"server_name admin.example.com;", "server_name webmail.example.com;",
} {
if !strings.Contains(string(nginx), want) {
t.Errorf("nginx-inbuxa.conf lacks %q", want)
}
}
for _, want := range []string{"reverse_proxy 127.0.0.1:8081", "disable_http_challenge", "import " + dir + "/proxy/Caddyfile.fragment"} {
if !strings.Contains(string(caddy), want) {
t.Errorf("Caddyfile.fragment lacks %q", want)
}
}
// A fragment is imported beside other sites: no global options block
for _, line := range strings.Split(string(caddy), "\n") {
if strings.TrimSpace(line) == "{" {
t.Error("the Caddyfile fragment has a global options block")
}
}
if s.GatewayIP != "172.31.253.1" {
t.Errorf("gateway = %s", s.GatewayIP)
}
}
func TestProxySnippetsLeaveOutWhatIsNotHere(t *testing.T) {
s := stack(true)
s.Webmail = false
out, err := WriteProxySnippets(t.TempDir(), *s)
if err != nil {
t.Fatal(err)
}
nginx, _ := os.ReadFile(filepath.Join(out, "nginx-inbuxa.conf"))
if strings.Contains(string(nginx), "webmail.example.com") {
t.Error("a webmail that isn't installed is in the nginx configuration")
}
}
@@ -0,0 +1,52 @@
# Written by the inbuxa installer {{.Version}} for {{.Domain}}.
#
# For the web server already on this machine: Caddy. Import it from your
# Caddyfile (`import {{.Dir}}/proxy/Caddyfile.fragment`) and reload. It has no
# global options block, so it can sit beside your own sites. The installer
# loads nothing and restarts nothing.
#
# Everything is passed to loopback: 8081 the mail server, 8082 the console,
# 8080 the webmail. Caddy gets certificates for the console and the webmail
# itself.
{{- if .ServesServer}}
# The mail server's names. Caddy uses TLS-ALPN-01 for them and leaves HTTP-01
# on port 80 to the mail server, which needs a certificate of its own for
# IMAP and SMTP: so neither answers the other's challenge.
{{join .ServerNames ", "}} {
tls {
issuer acme {
email {{.Email}}
disable_http_challenge
}
}
reverse_proxy 127.0.0.1:8081 {
flush_interval -1
}
}
{{range $i, $n := .ServerNames}}{{if $i}}, {{end}}http://{{$n}}{{end}} {
handle /.well-known/acme-challenge/* {
reverse_proxy 127.0.0.1:8081
}
handle {
redir https://{host}{uri} 308
}
}
{{- end}}
{{- if .Console}}
{{.ConsoleHost}} {
encode zstd gzip
reverse_proxy 127.0.0.1:8082
}
{{- end}}
{{- if .Webmail}}
{{.WebmailHost}} {
encode zstd gzip
reverse_proxy 127.0.0.1:8080 {
flush_interval -1
}
}
{{- end}}
@@ -0,0 +1,118 @@
# Written by the inbuxa installer {{.Version}} for {{.Domain}}.
#
# For the web server already on this machine: nginx. Include it from
# /etc/nginx/conf.d/ (or sites-enabled/), set each ssl_certificate pair to the
# certificate you have for those names, check it with `nginx -t`, and reload.
# The installer loads nothing and restarts nothing; this is yours to adjust.
#
# Everything is passed to loopback, where the installer put each program:
# 127.0.0.1:8081 the mail server's web side (JMAP, CalDAV, CardDAV,
# autoconfig, MTA-STS)
# 127.0.0.1:8082 the console
# 127.0.0.1:8080 the webmail
#
# The mail server trusts X-Forwarded-For from here, so every block sets it to
# the client's own address rather than passing on what the client sent.
{{- if .ServesServer}}
# Port 80 for the server's names: its own certificate challenges, which it
# answers itself once certificates are turned on in the console, and a
# redirect for everything else.
server {
listen 80;
listen [::]:80;
server_name {{join .ServerNames " "}};
location /.well-known/acme-challenge/ {
proxy_pass http://127.0.0.1:8081;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
}
location / {
return 308 https://$host$request_uri;
}
}
# The mail server's web side. Push arrives as a long-lived stream, so it is
# not buffered and not timed out early.
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name {{join .ServerNames " "}};
ssl_certificate /etc/ssl/inbuxa/{{.MailHost}}.fullchain.pem;
ssl_certificate_key /etc/ssl/inbuxa/{{.MailHost}}.key.pem;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:8081;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $http_connection;
proxy_buffering off;
proxy_read_timeout 1h;
}
}
{{- end}}
{{- if .Console}}
# The console: static files. It talks to the mail server from the browser,
# so nothing here proxies the API.
server {
listen 80;
listen [::]:80;
server_name {{.ConsoleHost}};
return 308 https://$host$request_uri;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name {{.ConsoleHost}};
ssl_certificate /etc/ssl/inbuxa/{{.ConsoleHost}}.fullchain.pem;
ssl_certificate_key /etc/ssl/inbuxa/{{.ConsoleHost}}.key.pem;
location / {
proxy_pass http://127.0.0.1:8082;
proxy_set_header Host $host;
}
}
{{- end}}
{{- if .Webmail}}
# The webmail. Push arrives as Server-Sent Events: flushed as written, and
# held open.
server {
listen 80;
listen [::]:80;
server_name {{.WebmailHost}};
return 308 https://$host$request_uri;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name {{.WebmailHost}};
ssl_certificate /etc/ssl/inbuxa/{{.WebmailHost}}.fullchain.pem;
ssl_certificate_key /etc/ssl/inbuxa/{{.WebmailHost}}.key.pem;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto https;
proxy_buffering off;
proxy_read_timeout 1h;
}
}
{{- end}}
+2
View File
@@ -390,6 +390,8 @@ func Build(f host.Facts, o Options) (Plan, error) {
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",
},
})
}
+13 -5
View File
@@ -59,7 +59,7 @@ type Wizard struct {
row int
shapes map[plan.Component]plan.Shape
proxy int // 0 caddy, 1 your own
proxy int // 0 caddy, 1 snippets for your own, 2 none
built plan.Plan
buildErr error
@@ -145,7 +145,7 @@ func (w *Wizard) Options() plan.Options {
o.ACMEEmail = strings.TrimSpace(w.fields[4].text())
o.Dir = strings.TrimSpace(w.fields[5].text())
o.Local = w.fields[6].text() == "yes"
o.Proxy = []string{"caddy", "none"}[w.proxy]
o.Proxy = []string{"caddy", "snippets", "none"}[w.proxy]
o.Choices = nil
for _, c := range []plan.Component{plan.Server, plan.Console, plan.Webmail} {
o.Choices = append(o.Choices, plan.Choice{Component: c, Shape: w.shapes[c]})
@@ -449,9 +449,13 @@ func (w *Wizard) updateReach(k Key) {
}
switch k.Kind {
case KeyUp:
w.proxy = 0
if w.proxy > 0 {
w.proxy--
}
case KeyDown:
w.proxy = 1
if w.proxy < 2 {
w.proxy++
}
case KeyEnter:
w.next()
}
@@ -633,7 +637,8 @@ func (w *Wizard) viewReach(width int) ([]string, string) {
}
options := []struct{ name, about string }{
{"Caddy, managed by the installer", "It holds 80 and 443, gets certificates for every name, and passes the server's own certificate challenges through."},
{"Your own web server", "Nothing here takes 80 or 443. Point yours at 127.0.0.1:8081 for the server, 127.0.0.1:8082 for the console and 127.0.0.1:8080 for the webmail; certificates are yours to arrange."},
{"Your own web server, with its configuration written", "Nothing here takes 80 or 443. The installer writes an nginx configuration and a Caddyfile fragment for the web server you run, and trusts it in front of the suite; loading it is yours."},
{"Nothing in front", "Nothing here takes 80 or 443, and nothing is written. The server answers on 127.0.0.1:8081, the console on 127.0.0.1:8082, the webmail on 127.0.0.1:8080."},
}
for i, opt := range options {
mark := "( )"
@@ -867,6 +872,9 @@ func Summary(res *apply.Result, err error, problems []string) []string {
row("certificate", "issued by "+res.Certificate)
}
row("dns records", res.ZoneFile)
if res.ProxyConfig != "" {
row("proxy config", res.ProxyConfig+" (load it into your web server)")
}
return out
}