Files
pipelines/docs/install.md
T

174 lines
8.7 KiB
Markdown

# Installation
`./install.sh` sets up **Docker server + ntfy** by default. Use `--native` for
native binaries only. Native installation requires Go; Docker setup requires Docker
Compose and Python 3, and includes OpenCode in the persistent server container.
```sh
git clone https://git.a-wan.net/alan/pipelines.git
cd pipelines
./install.sh
# Explicit choices:
./install.sh --docker # complete server/ntfy setup, including provider login
./install.sh --native # binaries/skill only; honors GOBIN/GOPATH
```
Native mode installs `pipelines`, `pipelines-server`, and `pipelines-tui`. Go chooses the
destination using `GOBIN`, or the usual `GOPATH/bin` default. Put that directory
on PATH. No privileged operations, private dependency installation, login prompts,
Docker provisioning, service registration, or background processes are involved.
Re-running installation updates the binaries and bundled OpenCode skill without
changing databases, login, or OpenCode configuration files.
Docker mode prompts for the phone-facing ntfy base URL, explicit bind IP, and
timezone if it cannot be detected. It preserves an existing `.env`, bootstraps
the publishing/phone accounts and publishing token, builds the server, installs
the skill inside the container, and opens **container OpenCode provider login**
on first setup. Choose any supported provider; signup is handled by that provider.
Provider credentials remain in the `opencode-home` volume. Reinstalls skip login
after completed setup; `./install.sh --relogin` opens it again without
deleting accounts. The installer then starts/recreates the Compose services,
checks ntfy health through Pipelines, and sends an authenticated test notification.
It does not register an OS service, delete volumes, or seed pipeline definitions.
Phone reception/model inference are not verified by installation.
For fresh configuration you can supply `--ntfy-url https://ntfy.example.com
--bind-address 127.0.0.1 --timezone Europe/London --port 8081` directly to `./install.sh`.
Use a LAN/VPN interface IP instead of loopback for direct phone access; only use
plain HTTP on a trusted network. Existing `.env` settings are never silently
replaced. Docker is also the default without a terminal; setup fails rather than
silently falling back to native binaries if required setup input is unavailable.
Use an interactive terminal for first Docker/provider setup.
Install native mode as well if you want host CLI/TUI binaries; Docker mode installs
the server and CLI in its image. See [Docker setup](docker.md).
For a private repository, use your normal Git credentials and `GOPRIVATE`:
```sh
GOPRIVATE=git.a-wan.net go install git.a-wan.net/alan/pipelines/cmd/...@latest
pipelines skill install
```
For a system-wide command, build as your normal user and install the three binaries
into an administrator-selected bin directory using your normal system permissions.
Services and OpenCode accounts still run as the logged-in user, never as root.
The installer does not hardcode a system destination or run sudo.
## Start explicitly
```sh
pipelines serve # foreground server; Ctrl+C stops it
# In another terminal:
pipelines
```
The server listens on loopback. Change into your repository and run a pipeline
there; the client sends its current directory to the server. The server's own
working directory does not restrict which repositories you can use. Model tool
permissions and approved edit paths remain separate, per-run/stage controls.
The SQLite database uses the standard user data location, honoring `XDG_DATA_HOME`
when set. On macOS it uses the user Application Support directory. `-db FILE`
selects another database, including an existing one; nothing is imported or moved
automatically. `pipelines serve --help` prints the actual defaults on your machine.
Drafts use the OS user cache; `PIPELINES_DRAFT_DIR` overrides that location.
## Optional autostart
Stop any existing foreground or legacy server first, then explicitly configure
the OS user service:
```sh
pipelines service enable
pipelines service status
```
This starts the server now and at subsequent logins. Linux uses
`systemctl --user`; macOS uses a LaunchAgent in your user `Library/LaunchAgents`.
There is no sudo, Docker dependency, or second supervisor. `--db`
and `--addr` select the database/listen address, just like foreground startup.
Re-run enable to update the definition and restart with the new settings.
```sh
pipelines service enable --print # preview only
pipelines service disable # stop and remove
```
Setup records the current PATH, HOME, XDG directory overrides, selected OpenCode
executable, and supported ntfy URL/token-file settings in a private service file.
It does not copy provider credentials or the rest of the shell environment.
Use `PIPELINES_NTFY_TOKEN_FILE`, not an inline token. Re-run enable after changing
these settings or moving binaries. Relative database/token-file paths are resolved
at configuration time. Services do not read your shell startup files.
On Linux this is **login autostart**, not automatically boot-without-login.
If needed, explicitly enable lingering using your system's normal administration
policy (`loginctl enable-linger "$USER"`). Pipelines does not change that policy.
macOS LaunchAgents likewise require a user login. Windows autostart is unsupported.
Use `journalctl --user -u pipelines.service` for Linux logs. On macOS inspect
`pipelines service status`; run `pipelines serve` in the foreground for diagnostics.
## OpenCode
Use your existing `opencode` on PATH, or set `PIPELINES_OPENCODE` to an explicit
executable. No OpenCode version is required just to install binaries. At runtime:
- The standard/native API release uses an owned, authenticated loopback
`opencode serve` process, scoped to the requested repository and using the
existing user's configuration/login. The API, not a version number, is checked.
- A CLI advertising `api` uses the V2 command interface and its normal discovery.
- Both adapters select the pipeline's configured model explicitly and preserve
stage tool permissions. Native `shell` permissions map to OpenCode's `bash`.
- Audited native sessions record their backend and a private service reference
so recovery addresses the same service, rather than a new unrelated instance.
- `new`/`edit` open the normal interface directly with `@pipelines` and a draft
context-file reference. The skill handles questions and draft validation inside
OpenCode; no preliminary session/API calls or instruction preload are performed.
The global skill is installed in `$XDG_CONFIG_HOME/opencode/skills/pipelines`,
or the normal `~/.config/opencode/skills/pipelines` default. Only unchanged files
previously installed by Pipelines are updated. A user-managed/modified skill is
never overwritten; preserve or rename it before running `pipelines skill install`.
Installation does not require OpenCode itself. Uninstall retains the skill and drafts.
The bundled examples retain `opencode-go/deepseek-v4.1-flash`. Availability and
authentication for that model are runtime requirements, not installation checks.
No login or provider credentials are copied or exported by Pipelines.
## Optional notifications
Full Docker installation configures this automatically via `./install.sh --docker`.
For native mode, use an existing ntfy server or the Docker setup in [docs/ntfy.md](ntfy.md).
Configure `PIPELINES_NTFY_URL`, `PIPELINES_NTFY_PUBLIC_URL`, and a publishing token
via `PIPELINES_NTFY_TOKEN_FILE` in the server's environment. Keep secrets out of
pipeline definitions. Use HTTPS or an encrypted VPN for phone access; do not
expose an unauthenticated pipeline server or HTTP credentials to untrusted networks.
## Uninstall
Disable autostart with `pipelines service disable` if configured, or stop the
foreground server first, then:
```sh
pipelines uninstall
# or pipelines uninstall --yes
```
Only Go binaries whose embedded build metadata matches this repository are
removed from the current command's bin directory. History, drafts, OpenCode,
and optional ntfy data remain untouched. Use the permissions appropriate to your
chosen bin directory. Custom database paths cannot be inferred, so uninstallation
does not purge data.
## Existing managed installations
The previous Python-supervised setup is retained only for explicit legacy use.
Set `PIPELINES_PREFIX` to its existing directory for its lifecycle commands;
no command infers that directory from an executable location. The old
`--system-command`, provisioning, and autostart installer flags have been removed.
To migrate, stop the old server first, install normal Go binaries, and start with
`pipelines serve -db EXISTING_DATABASE`. Keep the old
data and credentials until you have verified the new setup. There is no automatic
purge, database move, login migration, or shared OpenCode service modification.