139 lines
6.5 KiB
Markdown
139 lines
6.5 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
|
|
go install ./cmd/...
|
|
# ./install.sh is a thin wrapper around the same command.
|
|
```
|
|
|
|
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 without changing data or configuration.
|
|
|
|
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
|
|
```
|
|
|
|
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 -workspace-root "$HOME" # foreground server; Ctrl+C stops it
|
|
# In another terminal:
|
|
pipelines
|
|
```
|
|
|
|
The server listens on loopback. Limit `-workspace-root` to trusted repositories;
|
|
repeat the flag for multiple roots. Omission permits only the server's working
|
|
directory. Runtime repository requests cannot escape these roots via symlinks.
|
|
|
|
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 --workspace-root "$HOME"
|
|
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. Choose a narrower root
|
|
if possible; repeat `--workspace-root` for multiple trusted directories. `--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 --workspace-root "$HOME/repos" --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` preload authoring instructions before opening the normal interface.
|
|
Native preloading uses `noReply=true`; V2 uses explicit skill activation.
|
|
|
|
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 -workspace-root TRUSTED_ROOT`. 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.
|