Files
pipelines/docs/install.md
T

102 lines
4.5 KiB
Markdown

# Install and test
Run as your normal user, **not** with sudo. Requires Python 3, a running Docker
daemon with Compose, and OpenCode V2 connected to OpenCode Go. Source installs
also require Go 1.27+. Platform archives contain the server, CLI, and TUI binaries. If OpenCode
is absent and npm is available, the installer offers a private pinned CLI install;
Docker itself is not installed automatically.
```sh
./install.sh
# Optional: expose the command in /usr/local/bin (sudo for the symlink only):
./install.sh --system-command
```
Setup prompts for phone username, password, and global notification topic. Blank
password generates one. `--yes` accepts defaults and generates a password;
`--password-file PATH` supplies one without putting it in shell arguments.
Phone connection details are saved privately in
`~/.local/share/pipelines/secrets/phone-login.txt`. Configure the ntfy phone app
with those credentials and subscribe to that topic. Phone delivery still needs
an actual device test. Prefer Tailscale or HTTPS; HTTP exposes credentials on an
untrusted network.
The native server and Docker ntfy are managed together:
```sh
pipelines # dashboard; b opens rendered templates
pipelines status
pipelines doctor
pipelines stop
pipelines start
pipelines restart
pipelines logs
```
Default command path is `~/.local/bin/pipelines`; add `~/.local/bin` to PATH if
needed. It points directly to a compiled Go binary, not a shell launcher.
Source installation builds all binaries with `go install`. Service registration uses
per-user launchd on macOS or systemd on Linux.
`--no-autostart` uses background supervision instead. Services retain the current
user's OpenCode config/login, without exporting credentials into Docker.
`--system-command` is a system PATH shortcut to this user's install, **not** a
shared multi-user service. Other users should install their own instance.
## Run in a repository
```sh
cd ~/repos/my-project
pipelines run # fuzzy pipeline picker, then prompt
pipelines run "bug fix" # prompt composer
pipelines run "bug fix" "Fix the layout" # explicit execution confirmation
pipelines run "bug fix" "Fix the layout" --yes
```
The composer supports multiline typing/paste: **Enter** adds a newline,
**Ctrl+S** or **Alt+Enter** continues. The current directory is recorded as the
run workspace. After confirmation, the live run inspector opens.
`--yes` requires a supplied name and nonempty prompt and does not approve tools.
Use `--allow-tools` with `--yes` to explicitly approve declared tools;
`--write-paths "internal/example.go"` grants exact existing Go-file edits.
Current edit tooling is Go-specific, not arbitrary repository editing.
Installer workspace roots default to the user's home directory. Restrict them
using repeatable `--workspace-root ~/repos` on initial setup. Runs outside those
roots (including symlink escapes) are rejected by the server. Raw native servers
default to their working directory; add `-workspace-root` to permit other repos.
Do not expose the unauthenticated pipeline server to untrusted users.
## Templates and data
New databases are empty. Press **b** on Home or use `:templates` to browse optional
examples, with rendered Markdown previews and **v** for source. Select a template,
choose a unique name, edit it in `$VISUAL`/`$EDITOR` (or an available fallback),
then explicitly submit. Existing names cannot be overwritten by this flow.
Submitting a scheduled template activates its schedule; previewing never does.
Uninstall retains pipeline history, credentials, and the isolated ntfy volume:
```sh
./uninstall.sh
# Explicitly delete this installation's retained data too:
./uninstall.sh --purge
```
Reinstall at the same prefix to reuse retained data. Host OpenCode remains
separate. Partial installations require inspection or explicit purge before retry.
Use `--prefix PATH --bin-dir PATH --server-port PORT --ntfy-port PORT` for isolated
testing; each prefix has its own Compose project and volume.
## Tester archives
```sh
python3 scripts/package.py --platform darwin-arm64 --version 0.1.0-beta.1
# Also: darwin-amd64, linux-amd64, linux-arm64, source
```
Outputs go to `dist/` with a SHA-256 checksum. Archives include only allowlisted
source, examples, docs, installation scripts, and optional release binaries—no
databases, runtime drafts, `.env`, logs, or secrets. Extract, then run `./install.sh`.
Cross-built Linux binaries, Linux systemd, system PATH installation, and automatic
npm installation require separate execution tests; build success is not a runtime test.