Deploying from a release bundle¶

Install or upgrade ironshep-core / ironshep-edge on a Linux host from a pre-built release instead of compiling on the host. This is the fast path: no Rust toolchain, no build dependencies, no cargo build on the target — just download, verify, drop in place, restart.

First-time install from a release → this doc (skips the build steps in 02-core-host.md / 03-edge-host.md; you still do the DB, certs, config, and firewall steps from those).
Upgrading a host that already runs a source build → the swap-and-restart in 04-redeploy.md applies unchanged; just take the binary from a release bundle instead of target/release/.

Releases are cut by CI. Everything below assumes a tag has been pushed and the pipeline has published its Release.

How a release gets made (one-time, by a maintainer)¶

Each repo has a .gitlab-ci.yml that builds on Rocky Linux 9 — the same glibc (2.34) as RHEL 9 — so the binary runs on RHEL / Rocky / Alma / CentOS Stream 9 (x86_64) without a "glibc too new" error. Pushing a semver tag triggers a build + a GitLab Release with the deploy bundle attached:

# in the ironshep-core (or ironshep-edge) checkout, on main, tree clean:
git tag v0.2.0
git push origin v0.2.0

The pipeline runs test → build → release:

cargo test --release --locked
cargo build --release --locked, then packages ironshep-<core|edge>-v0.2.0-x86_64-linux.tar.gz + a .sha256
On the tag, uploads both to the project Package Registry and creates the Release (Deploy → Releases in GitLab), with the bundle linked as an asset.

Non-tag pushes to main still build and attach the bundle as a 30-day pipeline artifact (Build → Artifacts) — handy for testing a build before tagging. There's no manual binary-copying step for the maintainer; the tag is the whole release action.

What's in the bundle - core: ironshep-core binary, ironshep-core.service, core.toml.example, gen_certs.sh, install_db_rhel9.sh, sql/schema.sql, SETUP_RHEL9.md. - edge: ironshep-edge binary, ironshep-edge.service, edge.toml.example, the three helper scripts, and tools/ (simulators).

1. Download the bundle onto the host¶

From the project's Deploy → Releases page, copy the asset link for the tag you want, then on the target host:

VER=v0.2.0
# core (use ironshep-edge on the edge host):
BASE="https://gitlab.com/ironshep/ironshep-core/-/releases/${VER}/downloads"
curl -fL -O "${BASE}/ironshep-core-${VER}-x86_64-linux.tar.gz"
curl -fL -O "${BASE}/ironshep-core-${VER}-x86_64-linux.tar.gz.sha256"

If the project is private, either download in a browser you're logged into and scp the two files over, or pass a token: curl -fL --header "PRIVATE-TOKEN: <token>" -O <the Package Registry URL> (the Package Registry URL is on the release's asset link).

2. Verify the checksum — always¶

sha256sum -c ironshep-core-${VER}-x86_64-linux.tar.gz.sha256
# expect: ironshep-core-v0.2.0-x86_64-linux.tar.gz: OK

Don't skip this — it's the one check that the download is intact and is the build CI produced. Stop if it doesn't say OK.

3. Unpack¶

tar xzf ironshep-core-${VER}-x86_64-linux.tar.gz
cd ironshep-core-${VER}-x86_64-linux

4a. First-time install¶

Same install layout as the source-build docs — the only difference is the binary is already built.

# service account + dirs (idempotent; skip any that already exist)
sudo useradd --system --no-create-home --shell /sbin/nologin ironshep 2>/dev/null || true
sudo mkdir -p /opt/ironshep-core /etc/ironshep/certs

# binary
sudo install -o ironshep -g ironshep -m 0755 ironshep-core /opt/ironshep-core/ironshep-core

# config (edit before starting — DB URL, bind addr, notification settings)
sudo cp core.toml.example /etc/ironshep/core.toml
sudo chown root:ironshep /etc/ironshep/core.toml && sudo chmod 640 /etc/ironshep/core.toml

# systemd unit
sudo cp ironshep-core.service /etc/systemd/system/
sudo systemctl daemon-reload

You still need the surrounding setup from the source-build docs — the release bundle only replaces the build:

Database (01-database-host.md) — the bundled install_db_rhel9.sh and sql/schema.sql are the same ones that doc drives. Do this first; put the resulting DB URL in core.toml.
Certificates (02-core-host.md) — mTLS is mandatory. Generate with the bundled gen_certs.sh and place under /etc/ironshep/certs (update the paths in core.toml). The edge's certs are minted here too.
Firewall / SELinux — as in 02/03.

Initialize the schema, then start:

sudo -u ironshep /opt/ironshep-core/ironshep-core --config /etc/ironshep/core.toml --init-db
sudo systemctl enable --now ironshep-core
systemctl status ironshep-core --no-pager
journalctl -u ironshep-core -f          # expect: "listening on 0.0.0.0:50051"

The edge is the same shape against /opt/ironshep-edge and /etc/ironshep/edge.toml — no DB, no --init-db. It needs ca.crt + this edge's cert/key from the core host (see 03-edge-host.md), then sudo systemctl enable --now ironshep-edge.

4b. Upgrade an installed host¶

Config, certs, DB, and the systemd unit are already in place and are not touched — an upgrade is just the binary. Use a temp-name + mv so replacing the running binary can't fail with "Text file busy" (identical to 04-redeploy.md, only the binary source differs):

# keep the current binary for rollback
sudo cp /opt/ironshep-core/ironshep-core /opt/ironshep-core/ironshep-core.prev

sudo install -o ironshep -g ironshep -m 0755 ironshep-core /opt/ironshep-core/ironshep-core.new
sudo mv /opt/ironshep-core/ironshep-core.new /opt/ironshep-core/ironshep-core
sudo systemctl restart ironshep-core
journalctl -u ironshep-core -f

If the release included a schema change, apply it after restarting — it's idempotent and additive:

sudo -u ironshep /opt/ironshep-core/ironshep-core --config /etc/ironshep/core.toml --init-db

Rollback is the swap back you saved above:

sudo mv /opt/ironshep-core/ironshep-core.prev /opt/ironshep-core/ironshep-core
sudo systemctl restart ironshep-core

Because CI builds every tag from a committed Cargo.lock, an older release is byte-reproducible enough to trust as a rollback target — or just download the previous tag's bundle again.

Contract skew: if the release changed proto/ingest.proto, upgrade both core and edge (proto3's add-only rule lets you do them one at a time — see 04-redeploy.md § When the wire contract changed).

When to build from source instead¶

The release bundle targets x86_64 EL9. Build from source (02/03) when you need a different target — arm64, an older/newer glibc, a musl-static "runs anywhere" binary — or you want to deploy an untagged revision. The source path and the release path produce the same binary for the same commit; releases just save every host from installing a toolchain.

Quick reference¶

You have	Do
Fresh host, want a tagged build	§1–3 download+verify+unpack, then §4a (plus DB/certs/firewall from `01`–`03`)
Installed host, new tag out	§1–3, then §4b (binary swap + optional `--init-db`)
Need arm64 / musl / an untagged commit	build from source (`02`/`03`)
Bad upgrade	`mv …prev` back + restart (§4b rollback)
Cut a new release (maintainer)	`git tag vX.Y.Z && git push origin vX.Y.Z`