Files

T

Jon Chery 85963dc320 feat(P02): install.sh 1-liner + in-place update + README quickstart

REQ-043: install.sh pulls release binary from public Gitea URL.
  User-level default (~/.local/bin/orca), --system for system-level
  (/usr/local/bin/orca). Defaults to latest release; --version pins.
  Env-overridable GITEA_URL/OWNER/REPO for testability.

REQ-044: in-place update detects existing binary, reads version via
  'orca version --json', prints update message, overwrites binary,
  preserves namespace dir (config/db/certs). Idempotent re-install.

REQ-016 (completion): README quickstart now documents the 1-liner
  install + --system variant + update-in-place pattern.

Tests: 8/8 pass in scripts/install_test.sh (real public Gitea releases,
  no mock server; timeout-guarded to prevent hangs).

Docs: docs/install.md covers user/system install, version pinning,
  in-place update, uninstall, troubleshooting.

---ci---
project: orca
phase: 2
milestone: v0.5
status: verify
---/ci---

2026-08-03 18:49:50 +00:00

3.6 KiB

Raw Blame History

Install Guide

Orca is distributed as a single binary via a 1-liner installer that pulls from the public Gitea release artifacts. This guide covers user-level install, system-level install, in-place updates, version pinning, and troubleshooting.

Prerequisites

A Linux system with curl and tar installed.
For user-level install: write access to ~/.local/bin/.
For system-level install: root (sudo) access.

User-Level Install (Default)

curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash

This installs:

Binary: ~/.local/bin/orca
Namespace root: ~/.orca/ (created by orca init)

If ~/.local/bin is not on your PATH, add it:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

System-Level Install

curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | sudo bash -s -- --system

This installs:

Binary: /usr/local/bin/orca
Namespace root: /root/.orca/ (created by orca --system init)

The --system flag requires root (uid 0). It errors if ORCA_HOME is already set to a conflicting value.

Initialize State

After installing, initialize the local state directory:

# User-level
orca init

# System-level
orca --system init

This creates the namespace root directory (~/.orca or /root/.orca).

Version Pinning

By default, the installer fetches the latest release. To pin a specific version:

curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash -s -- --version v0.4.2

In-Place Update

Re-running the installer updates the binary in place while preserving your config, database, and certificates in the namespace dir:

curl -fsSL https://git.cloudinit.dev/coreci/orca/raw/branch/main/scripts/install.sh | bash

Output:

install: ✓ updated orca from v0.4.1 to v0.4.2 at /home/user/.local/bin/orca

The installer:

Detects the existing binary at the install path.
Reads its version via orca version --json.
Downloads the new release.
Overwrites the binary.
Never touches the namespace dir (~/.orca or /root/.orca).

Uninstall

# Remove the binary
rm ~/.local/bin/orca          # user-level
sudo rm /usr/local/bin/orca   # system-level

# Optionally remove state (THIS DELETES YOUR DATABASE + CERTS)
rm -rf ~/.orca                # user-level
sudo rm -rf /root/.orca       # system-level

Troubleshooting

`install: error: --system requires root`

The --system flag requires root. Re-run with sudo:

curl -fsSL ... | sudo bash -s -- --system

`install: error: --system conflicts with ORCA_HOME=...`

ORCA_HOME is set to a non-system path. Either unset it or drop --system:

unset ORCA_HOME
curl -fsSL ... | sudo bash -s -- --system

`install: error: could not find asset orca-vX.Y.Z-linux-amd64.tar.gz`

The requested version does not have a Linux release asset. Check available releases at https://git.cloudinit.dev/coreci/orca/releases.

`install: error: unsupported architecture: ...`

The installer supports amd64 (x86_64), arm64 (aarch64), and armv7. Contact the maintainers if you need another architecture.

`~/.local/bin is not on your PATH`

Add it to your shell profile:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
source ~/.bashrc

3.6 KiB Raw Blame History