add icon token subdir, Docker, SPEC/AGENTS, initial commit

2026-08-16 20:13:42 +07:00
commit 73eeab7f63
@@ -0,0 +1,39 @@
+# AGENTS.md — IDRS API server
+
+Project conventions and operational gotchas for agents working in this repo.
+
+## Layout
+- `app/main.py` — FastAPI app: public endpoints `GET /api/getTokenInfo`, `GET /api/version/android`, `GET /img/token/<filename>`; mounts `/static`; startup calls `db.init_db()`.
+- `app/admin.py` — sqladmin panel: `TokenAdmin` (custom WTForms form, `on_model_change`), `VersionAdmin`, `create_admin(app)`. Upload icons saved under `app/static/icons/token/` with `iconUrl = {IDRS_PUBLIC_URL}/img/token/<filename>`.
+- `app/models.py` — SQLAlchemy `Token`/`Version`, engine, `SessionLocal`, `ICON_DIR`, `DB_PATH` (env `IDRS_DB_PATH`).
+- `app/db.py` — seed from `tokenList.json`/`versionAndroid.json` (once, empty DB only).
+- `app/auth.py` — `AdminAuthBackend`, fail-closed creds.
+- `tokenList.json` / `versionAndroid.json` — seed source (read-only after seed).
+
+## Environment / secrets
+- `.env` (gitignored) → `ADMIN_USERNAME`, `ADMIN_PASSWORD`, `IDRS_PUBLIC_URL` (default `https://idrs.databisnis.id`). Test creds `admin`/`testpass123` — change before exposure.
+- `.session_secret` (gitignored, auto-generated 0600) if `IDRS_SESSION_SECRET` unset.
+- NEVER bake `.env` into the Docker image; pass via `--env-file` / `-e`.
+- Untracked, never commit: `.env`, `.session_secret`, `idrs.db*`, `venv/`, `app/static/icons/*`.
+
+## Run (local)
+- `./run.sh` loads `.env` then `uvicorn app.main:app --host 127.0.0.1 --port 8000`.
+- Start detached: `setsid nohup ./run.sh < /dev/null > /tmp/opencode/idrs.log 2>&1 & disown` (plain `&` hangs).
+- Sanity-import: `./venv/bin/python -c "from app import main; print('IMPORT_OK')"`.
+
+## Docker
+- `docker build -t idrs-api .`
+- Run with volumes: `-v idrs-data:/app/data -v idrs-icons:/app/app/static/icons`, env via `--env-file .env`.
+- MUST use a single uvicorn worker (in-memory starlette sessions → `--workers >1` breaks login).
+- DB + uploaded icons persist in the volumes across container recreate; code changes need an image rebuild.
+
+## Verification
+- curl login: `POST /admin/login` with `-c/-b` cookie jar; then curl admin endpoints / uploads with the jar.
+- Assert `/img/token/<f>` returns `image/png`; HTML/oversize uploads rejected (400).
+
+## Operation gotchas
+- NEVER `pkill -f uvicorn` broadly — a separate user process runs uvicorn on port 7000. Kill only the port-8000 PID (`ps -ef | grep "uvicorn app.main:app --host 127.0.0.1 --port 8000"`).
+- Local server binds 127.0.0.1:8000. Host ports 8080/8100 are taken by other services.
+
+## Spec
+- Canonical invariants and task status live in `SPEC.md` (§V invariants, §T tasks, §B bug log). Keep it updated when behavior changes; check §V before modifying.