148 lines
6.9 KiB
Markdown
148 lines
6.9 KiB
Markdown
# Installation
|
|
|
|
Installation requires **Go only**. OpenCode is needed when authoring or executing
|
|
model stages. Docker/ntfy is optional and is configured separately.
|
|
|
|
```sh
|
|
git clone https://git.a-wan.net/alan/pipelines.git
|
|
cd pipelines
|
|
./install.sh
|
|
# Equivalent: go install ./cmd/... && pipelines skill install
|
|
```
|
|
|
|
This 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.
|
|
|
|
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
|
|
|
|
Use an existing ntfy server or the optional 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.
|