81 lines
3.5 KiB
Markdown
81 lines
3.5 KiB
Markdown
# 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.
|