# 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.