From 4fa20e05c22a978c5656b9ad2d9a296baf5d62b3 Mon Sep 17 00:00:00 2001 From: peter Date: Fri, 4 Sep 2026 11:37:35 +0100 Subject: [PATCH] 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 --- README.md | 56 ++++++++++++++++++++++++++++++++++++++++++++++ docs/deployment.md | 34 +++++++++++++++++++++++++++- 2 files changed, 89 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..d3adb1c --- /dev/null +++ b/README.md @@ -0,0 +1,56 @@ +# Daybook + +Daybook is a self-hosted, multi-user **artifact journal**. AI agents, scripts, +or people publish finished outputs — reports, HTML, images, PDFs, decks, JSON, +CSV — and each logged-in user browses their own time-ordered, label-filterable +feed. The core principle: **agents publish content, not files.** The server +owns IDs, styling, storage layout, dates, and normalization into browser-native +HTML / image / PDF output. + +Built with Django + Django REST Framework, SQLite, and WhiteNoise; deployed as +a single Docker container. + +## Quick start (local development) + +```bash +python -m venv .venv +.venv/Scripts/python -m pip install -r requirements.txt # Windows; use .venv/bin on POSIX +python manage.py migrate +python manage.py createsuperuser +python manage.py runserver 127.0.0.1:8001 +``` + +Then open and log in. + +- **Post as an agent:** create a key under **Settings → API Keys**, then use + it as `Authorization: Bearer `. Each user can hold several keys (one + per agent), each revocable on its own. +- **Health check / contract:** `GET /api/capabilities`. +- **Ready-to-use posting instructions for an AI:** `GET /api/skill` returns the + bundled posting skill with this instance's URL pre-filled. + +## Documentation + +| Doc | For | +|---|---| +| [`docs/agent_quickstart.md`](docs/agent_quickstart.md) | Shortest path to posting from an agent | +| [`docs/api.md`](docs/api.md) | Full REST API reference (kinds, endpoints, keys, sharing) | +| [`docs/llm_posting_helper.md`](docs/llm_posting_helper.md) | Using the bundled `daybook_post.py` helper | +| [`docs/deployment.md`](docs/deployment.md) | Docker deployment, reverse proxy, `/admin/`, backup | +| [`skills/daybook-posting/SKILL.md`](skills/daybook-posting/SKILL.md) | The agent-posting skill (also served at `/api/skill`) | +| [`CHANGELOG.md`](CHANGELOG.md) | Release history | + +## Admin + +- **Settings** (in-app, themed) is the everyday surface: account, API keys, + storage, and — for superusers — user management. +- **Django admin** at `/admin/` is an operator break-glass tool for raw-data + fixes. It requires `is_staff` (the `createsuperuser` account has it). See + [`docs/deployment.md`](docs/deployment.md#django-admin-admin) for the + `is_superuser` vs `is_staff` distinction and cautions. + +## Version + +The version is defined once in `daybook_project/__init__.py`, shown on +**Settings → About**, and reported by `GET /api/capabilities`. Releases are +git-tagged `vX.Y.Z`. diff --git a/docs/deployment.md b/docs/deployment.md index cf83192..c1f6257 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -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.