inbuxa join: the console and the webmail here, for a server elsewhere #16

Merged
jcoffey-dev merged 1 commits from feat/join into main 2026-10-12 13:23:22 +00:00
Owner

Stacked on #15 (server on the host), which is stacked on #14. This branch includes both, so merge #14, then #15, then this. Needs inbuxa-server #195 (inbuxa:FrontEnds) in a release before join works against a real server; until then it refuses with "needs a release newer than 2026.10.10.1".

inbuxa join https://mail.example.com --key KEY installs the console and webmail here, for a server on another machine.

How it works

  • The key: the server is reached only over its own HTTPS, with an API key made in the console. The key can come from --key - (stdin) or INBUXA_JOIN_KEY, so it stays out of shell history, and it's never written to disk. There's no SSH and nothing done by hand on the server machine.
  • Registration: the front ends' addresses, plus a webmail client secret generated here, go into inbuxa:FrontEnds. That registers their sign-in and allows the console's origin on every node, with no restart.
  • It asks first, dry runs included. It refuses, with the reason, when:
    • the key is wrong;
    • the server has no inbuxa:FrontEnds;
    • the server already lists a different console or webmail (--replace overrides);
    • the server's environment sets the webmail's secret.
  • Then it:
    1. installs the console and webmail containers, with Caddy for their names only;
    2. registers them;
    3. exempts the webmail's address from the server's auto-ban: what its name resolves to, loopback for a loopback server, or --exempt-address;
    4. checks that the server answers the console's CORS preflight.
  • Re-runs: a second join with the same addresses converges. It records serverUrl in the install record, and refuses on a machine that runs the server itself.
  • Compose: learns the remote-server layout. Container and host-server installs render as before (a comment wording aside).
  • INBUXA_SERVER_BINARY: installs a server build instead of the release, for testing server changes. SERVER_BINARY= in e2e/vm/run.sh passes one into the VM.

Tests

  • Unit tests: JoinCheck against a fake server (good key, wrong key, old server, other console or webmail listed, --replace, environment-owned secret, console-only join) and both new compose layouts.
  • e2e/cases/join.sh: 24/24 on Debian 13 against a debug build of server #195. One VM plays both machines: the server is installed alone, then an API key is made, then the install record is set aside, then the front ends join into their own directory. It checks:
    • the wrong-key refusal, and that a dry run changes nothing;
    • the registration stored on the server, and the CORS preflight;
    • the console pointed at the server;
    • a person signing in to the joined webmail (code exchanged with the secret made here);
    • converging on a re-run, and refusing a different console without --replace.
  • install-local 26/26, install-host 43/43, install-public 20/20, status-export 16/16 and topology 28/28 all pass on this branch.

Not in this PR: removing a joined front end from the server (no uninstall yet), the docs page, and a console page for inbuxa:FrontEnds.

**Stacked on #15** (server on the host), which is stacked on #14. This branch includes both, so merge #14, then #15, then this. **Needs inbuxa-server #195** (`inbuxa:FrontEnds`) in a release before `join` works against a real server; until then it refuses with "needs a release newer than 2026.10.10.1". `inbuxa join https://mail.example.com --key KEY` installs the console and webmail here, for a server on another machine. **How it works** - **The key:** the server is reached only over its own HTTPS, with an API key made in the console. The key can come from `--key -` (stdin) or `INBUXA_JOIN_KEY`, so it stays out of shell history, and it's never written to disk. There's no SSH and nothing done by hand on the server machine. - **Registration:** the front ends' addresses, plus a webmail client secret generated here, go into `inbuxa:FrontEnds`. That registers their sign-in and allows the console's origin on every node, with no restart. - **It asks first,** dry runs included. It refuses, with the reason, when: - the key is wrong; - the server has no `inbuxa:FrontEnds`; - the server already lists a different console or webmail (`--replace` overrides); - the server's environment sets the webmail's secret. - **Then it:** 1. installs the console and webmail containers, with Caddy for their names only; 2. registers them; 3. exempts the webmail's address from the server's auto-ban: what its name resolves to, loopback for a loopback server, or `--exempt-address`; 4. checks that the server answers the console's CORS preflight. - **Re-runs:** a second join with the same addresses converges. It records `serverUrl` in the install record, and refuses on a machine that runs the server itself. - **Compose:** learns the remote-server layout. Container and host-server installs render as before (a comment wording aside). - **`INBUXA_SERVER_BINARY`:** installs a server build instead of the release, for testing server changes. `SERVER_BINARY=` in `e2e/vm/run.sh` passes one into the VM. **Tests** - Unit tests: JoinCheck against a fake server (good key, wrong key, old server, other console or webmail listed, `--replace`, environment-owned secret, console-only join) and both new compose layouts. - **`e2e/cases/join.sh`: 24/24 on Debian 13** against a debug build of server #195. One VM plays both machines: the server is installed alone, then an API key is made, then the install record is set aside, then the front ends join into their own directory. It checks: - the wrong-key refusal, and that a dry run changes nothing; - the registration stored on the server, and the CORS preflight; - the console pointed at the server; - **a person signing in to the joined webmail** (code exchanged with the secret made here); - converging on a re-run, and refusing a different console without `--replace`. - install-local 26/26, install-host 43/43, install-public 20/20, status-export 16/16 and topology 28/28 all pass on this branch. **Not in this PR:** removing a joined front end from the server (no `uninstall` yet), the docs page, and a console page for `inbuxa:FrontEnds`.
jcoffey-dev added 3 commits 2026-10-12 06:22:44 +00:00
The defaults were still server 2026.9.30.2, so a fresh install came up
without the fix for GHSA-m992-gp7g-wc2j. Console and webmail move to their
newest releases with it.

The plan also said each image was pinned by digest; they are pinned to a
release tag, as the comment beside the defaults explains, so it says that.
--server host now installs instead of refusing. The server is the release
binary for this machine's architecture, checked against a SHA-256 written
into the source (internal/release), run once with --version before it is
put in place, and installed as /usr/local/bin/inbuxa-server so it does not
collide with this program. It gets a system user, its configuration and
data in <dir>/server, its environment in <dir>/server.env (0600), and
inbuxa-server.service.

First boot is the container sequence. During setup a drop-in under /run
lets the server reach loopback and nothing else, and the step's credential
is in a root-only file rather than the unit. Then the listeners are fitted
to the host: plain HTTP to 127.0.0.1:8081, where a container install
publishes it; the server's own 443 listener removed, since the proxy holds
443; on --local every listener on loopback. The finished unit has
ConditionPathExists on the configuration, so a server that loses it stays
down instead of coming back in bootstrap mode.

The console and the webmail stay containers. Beside a host server the
webmail and Caddy share the host's network and reach it on loopback; the
console keeps the project network. A container install renders the same
files as before.

status and export report the server as host. A re-run converges; moving the
server between a container and the host is refused, not built yet.

e2e/cases/install-host.sh: 43 checks on Debian 13. install-local,
install-public, status-export and topology pass unchanged.
`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.
jcoffey-dev merged commit 6f374d05ce into main 2026-10-12 13:23:22 +00:00
jcoffey-dev deleted branch feat/join 2026-10-12 13:23:22 +00:00
Sign in to join this conversation.