270 lines
15 KiB
Markdown
270 lines
15 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 detects the computer's LAN IPv4 address and timezone automatically,
|
|
configures `http://LAN_IP:8090`, and binds both Docker services to `0.0.0.0` without asking
|
|
for networking settings (timezone falls back to UTC). On reinstall it updates only
|
|
the bind settings to `0.0.0.0`, refreshes the detected host LAN IP for Status,
|
|
and retains existing URLs/timezone/ports/credentials. It 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. Setup asks which connected provider/model to validate, then
|
|
requires a real, small **tool-free model response** before marking setup complete
|
|
(provider charges may apply). `--model PROVIDER/MODEL` selects it explicitly;
|
|
reinstall retests the saved selection. Login, discovery and validation prime
|
|
OpenCode's integration catalog in their own container/service. Discovery retries empty model
|
|
reads in the same container, avoiding a cold-start empty-catalog response.
|
|
An empty catalog is not proof of an invalid key; saved credentials are retained.
|
|
New drafts/templates inherit this selection;
|
|
published definitions and retry versions stay unchanged. Failed checks print
|
|
bounded, credential-redacted evidence and retain their OpenCode session.
|
|
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 is not verified by installation.
|
|
|
|
Docker setup mounts the host user's home and the installation checkout at their
|
|
original absolute paths, and runs Pipelines/OpenCode using that host user's UID
|
|
and GID. This makes a client invocation directory such as
|
|
`/home/tank/repos/pipelines` refer to the actual host checkout rather than an
|
|
unavailable container path or the unrelated image checkout at `/workspace`.
|
|
Stage permissions/edit scopes still apply; this is a filesystem mount, not a
|
|
workspace allowlist or automatic file transfer from another client computer.
|
|
For repositories outside those mounts, add a Compose bind at the same absolute
|
|
path. Reinstallation stops the old Pipelines service before changing ownership
|
|
of its managed data/auth/workspace volumes. It never recursively chowns the host
|
|
home/repository, deletes credentials, or removes volumes. Existing data/auth
|
|
volumes use `nocopy` so Docker cannot reset a freshly prepared empty volume's
|
|
ownership to the image UID. Setup verifies that the server can enter the host
|
|
checkout before reporting completion.
|
|
|
|
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`.
|
|
The defaults are ready for direct phone access on your trusted LAN. Only use
|
|
plain HTTP on a trusted network. Other existing `.env` settings are not replaced.
|
|
Docker is also the default without a terminal; setup fails rather than
|
|
silently falling back to native binaries if the LAN address cannot be detected.
|
|
Use an interactive terminal for first Docker/provider setup.
|
|
The Docker Pipelines API is unauthenticated: keep its port on a trusted network
|
|
and do not forward it to the Internet. For a manual loopback-only deployment,
|
|
set `PIPELINES_BIND_ADDRESS=127.0.0.1` after installation and use Compose directly.
|
|
Ctrl+C cancels cleanly without deleting configuration, credentials or volumes.
|
|
If Go is available, Docker setup also updates standard host CLI/TUI binaries and
|
|
the skill. Restart an already-running TUI to load the changes. Without Go, the
|
|
installer explicitly warns that the host client was not updated; use native
|
|
installation when Go is available. See [Docker setup](docker.md).
|
|
|
|
After ntfy verification, setup also checks the published Pipelines endpoint from
|
|
the host (when Go or a host CLI is available) and saves it in
|
|
`$XDG_CONFIG_HOME/pipelines/client.json`, or `~/.config/pipelines/client.json`.
|
|
Only `server_url` is updated; unrelated settings are preserved. CLI/TUI precedence
|
|
is `--url`, then `PIPELINES_URL`, then the saved default, then localhost:8080.
|
|
Docker defaults to port 8081, so an old native server on 8080 must not accidentally
|
|
become the client target. Setup warns if an environment override still selects
|
|
another address; it does not stop or delete that other server.
|
|
|
|
If Status says ntfy is **not configured**, check which Pipelines server the client
|
|
is reaching before reinstalling. On the Docker server computer:
|
|
|
|
```sh
|
|
docker compose port pipelines 8080
|
|
pipelines --url ws://127.0.0.1:8081/connect status --json
|
|
pipelines --url ws://127.0.0.1:8081/connect tui
|
|
```
|
|
|
|
Use the actual mapped port instead of 8081 if customized. On a different computer,
|
|
use the Docker host's LAN address instead of 127.0.0.1. The saved default applies
|
|
only on the computer/user that ran the installer. Phone reception remains untested
|
|
by these checks.
|
|
|
|
## Failure evidence and confirmations
|
|
|
|
TUI run/retry/cancel requests cannot be sent before their confirmation modal.
|
|
Draft creation/editing and opening a debugging session also require approval.
|
|
CLI mutations prompt with a default of No; `--yes` is explicit noninteractive
|
|
approval. The standalone TUI always keeps its modals, including with `-yes`.
|
|
|
|
`pipelines debug RUN_ID --no-open` retrieves the retained run plus read-only
|
|
OpenCode session evidence from the **server**, not the client's unrelated service.
|
|
Debug includes the exact pinned pipeline definition and full run snapshot directly.
|
|
Large context packets are retained in a private client cache file which OpenCode
|
|
is instructed to read, rather than discarding evidence or exceeding argument limits.
|
|
New failed operations retain operation, provider/model, executable, directory,
|
|
timing, exit/HTTP status and bounded stdout/stderr under `opencode_failures` in
|
|
the step transcript. Credentials are redacted, but project/provider messages may
|
|
still contain private context: review before sharing. Older failures cannot gain
|
|
discarded subprocess output retroactively; Debug attempts retained session reads.
|
|
|
|
Native OpenCode schema support is checked with a retained, deny-all, no-inference
|
|
POST/readback probe. OpenCode 1.18.35 accepts explicit formats but rejects their
|
|
stored messages on readback; affected backends omit `format` and require the same
|
|
strict local `{outcome, output}` validation. Compatible backends retain schema
|
|
mode with no automatic tool-replaying schema retries. The compatibility decision
|
|
and probe session are recorded, without rewriting published definitions/history.
|
|
For old format-bearing sessions whose HTTP readback fails, Debug uses read-only
|
|
`opencode export` with an exact session-ID check to recover original messages.
|
|
`StructuredOutputError` is surfaced directly; DSML/tool-call markup and flattened
|
|
results are rejected and retained, never silently interpreted as successful tool
|
|
execution or wrapped into a guessed result. Native HTTP evidence distinguishes
|
|
adapter/HTTP failures from actual subprocess exit codes.
|
|
|
|
To validate a model on the execution computer, run:
|
|
|
|
```sh
|
|
pipelines provider-check --model PROVIDER/MODEL
|
|
# Docker credentials are separate from host credentials:
|
|
docker compose exec pipelines pipelines provider-check --model PROVIDER/MODEL
|
|
```
|
|
|
|
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.
|