From c56e1b5b3a2f5b0639463325525187540cf1e7d4 Mon Sep 17 00:00:00 2001
From: Jean Chevronnet <reverse@noreply.git.devtronic.pro>
Date: Wed, 15 Jul 2026 11:45:17 +0000
Subject: [PATCH] Add deployment/operations guide

---
 Deployment.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 Deployment.md

diff --git a/Deployment.md b/Deployment.md
new file mode 100644
index 0000000..57f4242
--- /dev/null
+++ b/Deployment.md
@@ -0,0 +1,115 @@
+# Deployment
+
+Running Echo in production. Echo is the account and channel **authority** for a
+network, so the two things that matter most are durability and backups; both are
+covered below.
+
+## Build
+
+```sh
+git clone https://git.devtronic.pro/fedserv/echo.git
+cd echo
+cargo build --release        # protoc is vendored; no system protobuf needed
+```
+
+The binary is `target/release/echo`.
+
+## Install
+
+Run Echo as a dedicated unprivileged user, with `config.toml` and the event log
+in one data directory.
+
+```sh
+useradd --system --home-dir /opt/echo --shell /usr/sbin/nologin echo
+install -d -o echo -g echo /opt/echo
+install -o echo -g echo target/release/echo   /opt/echo/echo
+install -o echo -g echo config.example.toml   /opt/echo/config.toml   # then edit it
+install -m0644 scripts/echo.service /etc/systemd/system/echo.service  # edit paths/User
+systemctl daemon-reload
+systemctl enable --now echo
+```
+
+`scripts/echo.service` is a hardened unit (no new privileges, read-only system,
+private tmp, restart on failure). Adjust `ProtectSystem=strict` for a read-only
+root if you use a network mail relay rather than a local sendmail.
+
+## Configure the ircd link
+
+On the InspIRCd uplink, add a `<link>` block matching `[uplink]` / `[server]` in
+`config.toml` (name, SID, password, port). Echo links as its `[server] name`.
+The full `config.toml` reference is on the [Configuration](Configuration) page.
+
+## Durability
+
+Every committed change (registration, password, access, ban, …) is `fsync`'d to
+the event log before the command reports success, so a crash or power loss can
+not lose it. Compaction rewrites the log to a temp file, `fsync`s, and renames
+atomically, so a crash during compaction leaves the previous log intact. The log
+tolerates a truncated final line on load (it is skipped), which is what makes a
+plain file copy a safe backup.
+
+## Back up
+
+The event log is the whole database. Back it up regularly with
+`scripts/backup.sh` (gzips a timestamped snapshot and prunes old ones):
+
+```ini
+# /etc/systemd/system/echo-backup.service
+[Service]
+Type=oneshot
+User=echo
+Environment=ECHO_DATA_DIR=/opt/echo ECHO_BACKUP_DIR=/opt/echo/backups
+ExecStart=/opt/echo/scripts/backup.sh
+```
+
+```ini
+# /etc/systemd/system/echo-backup.timer
+[Timer]
+OnCalendar=hourly
+Persistent=true
+[Install]
+WantedBy=timers.target
+```
+
+`systemctl enable --now echo-backup.timer`. Copy backups off-box as well.
+
+## Restore
+
+```sh
+systemctl stop echo
+gunzip -c /opt/echo/backups/echo.db.<stamp>.jsonl.gz > /opt/echo/echo.db.jsonl
+systemctl start echo
+```
+
+## Upgrade
+
+```sh
+git pull
+cargo build --release
+install -o echo -g echo target/release/echo /opt/echo/echo
+systemctl restart echo
+```
+
+The on-disk format is an append-only event log; new event kinds are additive and
+old logs replay unchanged. Take a backup before upgrading regardless.
+
+## Monitor
+
+- `systemctl status echo` and `journalctl -u echo -f` (the log records write
+  failures, compaction, and account-store load at startup).
+- Optional `[jsonrpc]` HTTP endpoint exposes stats for a status page.
+- Systemd `Restart=on-failure` brings it back after a crash.
+
+## Federation (multiple nodes)
+
+Give each node a `[gossip]` bind + shared secret and a `[[peer]]` for the others
+(mutually-authenticated TLS via `[gossip.tls]`). Account identity replicates to
+every node; channel state stays local to the node that owns it. See
+[Federation](Federation). Start with a single node until you are comfortable.
+
+## Honest caveats
+
+Echo is pre-1.0. It is memory-safe, panic-free on the wire, and durable, but it
+has not yet accumulated a long production track record. Run it on your own
+network first, keep backups, and watch the logs. Declare a license before anyone
+else runs it.