From 126ec9c1f4e34e87cd5c8b3952bee379fc345f60 Mon Sep 17 00:00:00 2001 From: Daniel Gradman-Svendsen Date: Wed, 29 Jul 2026 13:11:59 +0200 Subject: [PATCH] Document repo install workflow for agents --- AGENTS.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 26 ++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dab4622 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,80 @@ +# Importarr Agent Instructions + +Importarr is owned as a Linux-ops-managed service repository. Treat this checkout as the source of truth for application code, deployment files, and local service installs. + +## Repository Source Of Truth + +- Work from `/srv/opencode-workspace/importarr` for Importarr code and deploy changes. +- Do not edit host-local legacy scripts as the normal workflow: + - `/usr/local/sbin/importarr-status.py` + - `/usr/local/sbin/manual-media-import.py` +- If an emergency hotfix is made outside the repo, backport it here immediately and reinstall from the repo. + +## Seamless Feature Workflow + +When asked to implement an Importarr feature, fix, UI change, deployment change, or operational behavior change: + +1. Inspect `git status --short --branch` before editing. +2. Implement the smallest correct repo change. +3. Run the narrowest useful verification, normally: + ```sh + .venv/bin/pytest -q + ``` + If shell deploy scripts changed, also run: + ```sh + sh -n deploy/systemd-install.sh && sh -n deploy/repo-upgrade.sh + ``` +4. Inspect `git diff` and ensure no secrets, raw `.env`, tokens, databases, or private material are included. +5. Commit and push completed Importarr changes by default unless the user explicitly asks not to publish or verification is blocked. +6. Install/restart from the repository so the running local service matches the repo: + ```sh + make upgrade-local + ``` +7. Verify the live service: + ```sh + make verify-live + ``` +8. If the live install fails, inspect `systemctl status importarr.service` and `journalctl -u importarr.service`; fix the repo, commit/push the fix, reinstall, and verify again. + +## Install Model + +- The service virtualenv lives at `/opt/importarr/venv`. +- The systemd unit runs `/opt/importarr/venv/bin/importarr` as the `importarr` system user. +- The package is installed from the repository into the venv using normal wheel/package install, not editable install. +- Do **not** use editable install for the system service: the unprivileged `importarr` user may not be able to read `/srv/opencode-workspace/importarr`, causing `ModuleNotFoundError` at startup. +- `/opt/importarr/repo-upgrade.sh` is the pull-and-reinstall helper for machines that should follow pushed `main`. + +## Local Commands + +```sh +make test +make install-systemd +make upgrade-local +make repo-upgrade +make verify-live +``` + +`make repo-upgrade` is for pulling already-pushed changes with `git pull --ff-only`. It refuses to run with uncommitted repo changes. + +## Runtime Defaults On This Host + +- Local URL: `http://127.0.0.1:8095/` +- Health: `http://127.0.0.1:8095/health` +- Status: `http://127.0.0.1:8095/api/status` +- Systemd service: `importarr.service` +- Env file: `/etc/importarr/importarr.env` +- SQLite state: `/var/lib/importarr/importarr.db` + +## Secret Handling + +- Prefer `*_FILE` settings for secrets, for example: + - `IMPORTARR_SAB_API_KEY_FILE` + - `IMPORTARR_AUTH_TOKEN_FILE` + - `IMPORTARR_RADARR_API_KEY_FILE` + - `IMPORTARR_SONARR_API_KEY_FILE` +- Never commit real env files, API keys, tokens, private keys, service databases, or backup data. +- Template files may list variable names with placeholder values or commented examples only. + +## Linux Ops Follow-Through + +For changes that materially alter the live service setup, ports, routes, monitoring, backup coverage, or host ownership, also follow the linux-ops documentation/systems-overview update rules. Do not mix unrelated pre-existing uncommitted changes from `linux-ops-docs` or `systems-overview` into Importarr commits. diff --git a/README.md b/README.md index 038862e..3c1349c 100644 --- a/README.md +++ b/README.md @@ -113,3 +113,29 @@ Importarr should not drift into host-local scripts. Treat the checked-out reposi 5. Verify the live service: `make verify-live`. Do not edit `/usr/local/sbin/importarr-status.py`, `/usr/local/sbin/manual-media-import.py`, or files copied out of the repo as the normal workflow. If an emergency live hotfix is unavoidable, backport it to this repository immediately and run the repo install workflow again. + +### Local install lessons learned + +- The live systemd service runs as the unprivileged `importarr` user. +- Do not install the system service with `pip install --editable /srv/opencode-workspace/importarr`; that can fail at startup if the service user cannot read the workspace checkout. +- The supported local service install is a normal package install from the repo into `/opt/importarr/venv`: + +```sh +sudo -n /opt/importarr/venv/bin/pip install --upgrade /srv/opencode-workspace/importarr +sudo -n systemctl restart importarr.service +``` + +- `deploy/systemd-install.sh`, `make upgrade-local`, and `/opt/importarr/repo-upgrade.sh` already use this supported model. +- After every implementation task that should affect the live local service, run: + +```sh +make upgrade-local +make verify-live +``` + +- If `make verify-live` fails, check: + +```sh +sudo -n systemctl --no-pager --full status importarr.service +sudo -n journalctl -u importarr.service -n 120 --no-pager +```