importarr/AGENTS.md

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.
• The live service is installed on dgsserver1 from a repo checkout at /opt/importarr/repo; gmk1 installs are not the public Importarr service.
• 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:

   .venv/bin/pytest -q
   

   If shell deploy scripts changed, also run:

   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 on dgsserver1 from the repository so the public service matches the repo:

   ssh -p 2222 opencode@dgsserver1 'sudo -n sh /opt/importarr/repo-upgrade.sh'
   

7. Verify the live service:

   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.

Gitea Issue Completion Workflow

When the user points an agent at an Importarr Gitea issue and asks to solve it, the expected end-to-end flow is mandatory unless the user explicitly says not to deploy:

1. Read the issue first, including comments and acceptance criteria.
2. Implement the smallest correct repo change on a dedicated issue branch when appropriate.
3. Run the narrowest useful tests/checks.
4. Commit and push the completed change to main or merge/push the issue branch as instructed.
5. Update the Gitea issue with what changed and the verification that ran, then close it when solved.
6. Update the dgsserver1 install from the pushed repo state:

   ssh -p 2222 opencode@dgsserver1 'sudo -n sh /opt/importarr/repo-upgrade.sh'
   

7. Restart/verify the dgsserver1 service from the repo-managed install and confirm the public URL:

   ssh -p 2222 opencode@dgsserver1 'sudo -n systemctl status importarr.service --no-pager -l'
   curl -fsS https://importarr.delphas.dk/health
   

If the worker timer is intentionally paused, do not re-enable it unless the issue explicitly includes worker scheduling or the user approves.

Install Model

• The service virtualenv lives at /opt/importarr/venv on dgsserver1.
• The status UI systemd unit runs /opt/importarr/venv/bin/importarr-status from the packaged repo install.
• The manual worker systemd unit runs /opt/importarr/venv/bin/manual-media-import from the packaged repo install.
• 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

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

• Public URL: https://importarr.delphas.dk/
• dgsserver1 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.