Jon Chery
85963dc320
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---
139 lines
3.6 KiB
Markdown
139 lines
3.6 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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:
|
|
```bash
|
|
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
## System-Level Install
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
1. Detects the existing binary at the install path.
|
|
2. Reads its version via `orca version --json`.
|
|
3. Downloads the new release.
|
|
4. Overwrites the binary.
|
|
5. **Never touches** the namespace dir (`~/.orca` or `/root/.orca`).
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
# 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`:
|
|
```bash
|
|
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`:
|
|
```bash
|
|
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:
|
|
```bash
|
|
echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.bashrc
|
|
source ~/.bashrc
|
|
```
|
|
|
|
## See Also
|
|
|
|
- [Namespace and Paths](namespace.md) — `ORCA_HOME`, `--system`, path layout.
|
|
- [Docker Guide](docker.md) — running orca in a container.
|
|
- [Development](../README.md#development) — building from source. |