kodi
217 lines
4.2 KiB
Markdown
217 lines
4.2 KiB
Markdown
# AGENTS.md — podman-mvp (WebUI + API)
|
|
|
|
## Goal
|
|
Primary goal: extend functionality and evolve the platform.
|
|
|
|
Feature development is the default workflow.
|
|
|
|
Refactoring is allowed when:
|
|
- it improves maintainability, OR
|
|
- it is required to implement a feature.
|
|
|
|
Refactoring must always:
|
|
- be proposed first,
|
|
- remain backward compatible,
|
|
- not change existing behaviour or API contracts without agreement.
|
|
|
|
---
|
|
|
|
## Repository structure
|
|
|
|
Backend (FastAPI modular monolith)
|
|
|
|
Bootstrap
|
|
- control/app.py (application bootstrap & router wiring ONLY)
|
|
|
|
System / platform router
|
|
- control/app_system.py
|
|
|
|
Feature routers
|
|
- control/app_containers.py
|
|
- control/app_pods.py
|
|
- control/app_networks.py
|
|
- control/app_files.py
|
|
- control/app_images.py
|
|
|
|
Shared infrastructure
|
|
- control/common.py
|
|
|
|
WebUI (static Apache)
|
|
- webui/html/index.html
|
|
- webui/html/assets/js/tabs/
|
|
- webui/conf/httpd.conf
|
|
|
|
### Backend architecture rule (HARD)
|
|
|
|
control/app.py is a bootstrap layer only.
|
|
|
|
It may:
|
|
- create FastAPI app
|
|
- include routers
|
|
- register startup events
|
|
|
|
It must NOT:
|
|
- contain feature endpoints
|
|
- contain system logic
|
|
- contain Podman or systemctl implementations
|
|
|
|
All endpoints belong in routers.
|
|
|
|
### Module ownership rule
|
|
|
|
If unsure where new logic belongs:
|
|
|
|
- shared logic → control/common.py
|
|
- system/platform logic → control/app_system.py
|
|
- feature logic → corresponding app_<feature>.py router
|
|
|
|
Never introduce new endpoints in control/app.py.
|
|
|
|
---
|
|
|
|
## Runtime architecture (IMPORTANT)
|
|
|
|
Application runs inside a Podman pod.
|
|
|
|
Pod created with:
|
|
|
|
podman pod create \
|
|
--name mvp-pod \
|
|
-p 8080:8000 \
|
|
-p 8081:8081 \
|
|
--userns=keep-id
|
|
|
|
|
|
### Backend container
|
|
|
|
Runs FastAPI control API with Podman access.
|
|
|
|
Created with:
|
|
|
|
podman run -d --pod mvp-pod \
|
|
--name mvp-backend \
|
|
--ipc=host \
|
|
--pid=host \
|
|
-e XDG_RUNTIME_DIR=/run/user/1000 \
|
|
-e DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus \
|
|
-v /run/user/1000:/run/user/1000:rw \
|
|
-v /run/user/1000/podman/podman.sock:/run/user/1000/podman/podman.sock:rw \
|
|
-v /home/kodi/.config/containers:/app/workloads:rw \
|
|
mvp-control:latest
|
|
|
|
|
|
Important notes:
|
|
- Backend communicates with Podman through unix socket.
|
|
- User-session Podman is used (not root).
|
|
- DBus access is required.
|
|
- Host PID/IPC namespaces are intentional.
|
|
|
|
Do NOT change these assumptions without proposal.
|
|
|
|
---
|
|
|
|
### WebUI container
|
|
|
|
Static Apache frontend.
|
|
|
|
podman run -d --pod mvp-pod \
|
|
--name mvp-webui \
|
|
-v $HOME/.config/podman-mvp/webui/html:/usr/local/apache2/htdocs:ro \
|
|
-v $HOME/.config/podman-mvp/webui/conf/httpd.conf:/usr/local/apache2/conf/httpd.conf:ro \
|
|
docker.io/library/httpd:2.4
|
|
|
|
Frontend is static JS calling API through proxy.
|
|
|
|
---
|
|
|
|
## Access
|
|
|
|
WebUI:
|
|
http://127.0.0.1:8081/
|
|
|
|
API (via proxy):
|
|
http://127.0.0.1:8081/api/
|
|
|
|
---
|
|
|
|
## Testing workflow (REQUIRED)
|
|
|
|
Always validate changes using curl.
|
|
|
|
Example:
|
|
|
|
curl -s http://127.0.0.1:8081/api/...
|
|
|
|
Before proposing implementation:
|
|
1. Analyse existing endpoints.
|
|
2. Confirm available data using curl tests.
|
|
3. Propose minimal change.
|
|
4. Provide verification curl commands.
|
|
|
|
---
|
|
|
|
## Contract rules (HARD)
|
|
|
|
- Never break existing API responses.
|
|
- Never rename or remove JSON keys.
|
|
- Maintain backward compatibility.
|
|
|
|
New functionality must be added via:
|
|
- new endpoints, OR
|
|
- optional response fields.
|
|
|
|
Security rules:
|
|
- No shell=True
|
|
- subprocess must be explicit and safe
|
|
- Never assume systemd states
|
|
|
|
Legacy notice:
|
|
allow_list / allowed_units.txt functionality has been removed
|
|
and must NOT be reintroduced.
|
|
|
|
---
|
|
|
|
## Change policy
|
|
|
|
Preferred workflow:
|
|
|
|
1. Analyse existing behaviour.
|
|
2. Propose small implementation plan.
|
|
3. Identify affected files.
|
|
4. Provide curl validation tests.
|
|
5. Implement after agreement.
|
|
|
|
Avoid:
|
|
- large rewrites
|
|
- structural changes without need
|
|
- hidden refactors.
|
|
All significant changes must follow PR_RULES.md workflow.
|
|
---
|
|
|
|
## UI direction
|
|
|
|
Target style:
|
|
Portainer-like dashboard UI.
|
|
|
|
Guidelines:
|
|
- tables and overview panels
|
|
- container status badges
|
|
- row-level actions
|
|
- minimalistic professional layout
|
|
|
|
Do NOT introduce large frontend frameworks without agreement.
|
|
|
|
---
|
|
|
|
## Coding style
|
|
|
|
Follow existing structure and conventions of each file.
|
|
|
|
Do not reformat unrelated code.
|
|
|
|
Minimize diff size whenever possible.
|
|
|
|
## Safety boundaries
|
|
|
|
Follow SAFE_FILES.md before modifying infrastructure or core files.
|