Docs: add README, document /admin/, refresh for v0.2.x

- Add a top-level README (repo had none): overview, local quick start,
  posting via API keys / the skill endpoint, a docs index, and the admin
  split.
- deployment.md: new "Django Admin (/admin/)" section covering how to log in,
  the is_superuser vs is_staff distinction, how to grant /admin/ access, and
  the raw-edit-bypasses-app-logic caution.
- Refresh constraint wording to per-user multiple API keys.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
peter 2026-09-04 11:37:35 +01:00
parent b382eb857b
commit 4fa20e05c2
2 changed files with 89 additions and 1 deletions

View file

@ -135,6 +135,37 @@ docker compose -f deploy/docker-compose.yml exec daybook python manage.py check
docker compose -f deploy/docker-compose.yml exec daybook sh
```
## Django Admin (`/admin/`)
Daybook ships Django's built-in admin at `/admin/` as an operator
break-glass tool — for raw-data fixes: reset a password, inspect or delete
any user's artifacts, adjust a quota, audit or revoke API keys. It is
separate from the in-app **Settings** area, which is the everyday product
surface (see the in-app guide / `docs/` for normal use).
**Logging in:** open `/admin/` and sign in with an account that has
`is_staff = True`. The account you create with `createsuperuser` has it (plus
full superuser rights). Note the two different admin concepts:
- `is_superuser` — Daybook's *in-app* admin (can reach Settings → Users).
- `is_staff` — can log into *Django's* `/admin/` site.
The `createsuperuser` account has **both**. A user promoted in-app via
Settings → Users ("Grant admin access") gets `is_superuser` only — so they
can administer Daybook through its own UI but **cannot** reach `/admin/`.
Regular users have neither. To grant someone `/admin/` access, set staff
explicitly:
```bash
docker compose -f deploy/docker-compose.yml exec daybook \
python manage.py shell -c "from django.contrib.auth.models import User; u=User.objects.get(username='NAME'); u.is_staff=True; u.save()"
```
**Caution:** the admin edits database rows directly and bypasses app logic —
e.g. deleting an artifact there does not clean up its files on disk the way
the app's own delete does. Use it for inspection and targeted fixes, not
routine management.
## Backup And Restore
Back up `deploy/data/` — it contains the SQLite database and all artifact
@ -198,6 +229,7 @@ Caddy: header_up X-Forwarded-Proto https
## Known MVP Constraints
- SQLite is used by default — fine for a single-VM self-hosted deployment.
- Per-user ingest tokens; no shared/global token.
- Per-user API keys (multiple per user, individually revocable); no
shared/global key.
- Reader/browser access requires login; feeds are private per user.
- Manual drag/drop upload and content revisions are deferred.