Cloudron DeepTutor

Cloudron package for DeepTutor — agent-native personalized AI tutoring.

The v1.7.x series makes DeepTutor modular: deeptutor alone is core (chat, CLI, SDK) and the web app plus every feature module are separate deeptutor-* distributions selected by the [full] profile. This package installs upstream's requirements/full.txt (the "Full app" profile) against the source tree, so every standard surface — chat, learning workspace, notebooks, Video Lessons, Learning/RAG, partners — is present out of the box.

v1.7.1

• Dependency delta vs v1.7.0 is one pure-Python package (markdown-it-py, newly a core dependency). No new compiled wheels, no interpreter or base-image change.
• Accounts. Users can change their own password from Profile, and accounts still on an admin-assigned temporary password get a change prompt. Two new endpoints (PUT /api/profile/password, PUT /api/admin/users/{username}/password).
• New creator capability (propose_creation tool) plus the /api/creations router, both owned by the core module so they are always present. Conversational creation drafts retain early work.
• Chat. Unsent composer drafts survive navigation; Little Tutor threads can recover, move or clear their source anchor without losing the thread.
• Video Lessons. Narration now prefers the Text-to-Speech provider configured in Settings and falls back to the bundled edge-tts. It also runs a browser layout check with targeted repairs. edge-tts narration needs no ffmpeg; the non-Edge providers do, so without ffmpeg narration always uses Edge — which is the documented fallback.
• Exports. Notebook flashcards export to Anki and Calendar events to iCalendar, both hand-rolled (no new dependency).
• Localization. Vietnamese, Japanese, Turkish and Brazilian Portuguese added, with RTL rendering and regional date formatting.
• Retrieval. PageIndex can use the configured Task model; LlamaIndex folder sync publishes one coherent version; hybrid retrieval drops zero-score BM25 hits.

v1.7.0

• Modular install. The package installs upstream's requirements/full.txt instead of the pre-1.7.0 partners.txt aggregate, and copies scripts/, pyproject.toml, build_metadata.py and build_support.py into /app/code. DeepTutor's modules/catalog.py only treats the feature modules as usable in a source checkout, which it detects by the presence of pyproject.toml and scripts/build_modules.py; without them the backend would boot with every module disabled and no API routes. A build-time assertion now fails the build if that gate ever closes.
• Video Lessons. Generation and playback run in the browser; the backend needs node and npm (Node 24 is present) and downloads its pinned Remotion rendering packages on first use into its runtime state directory under /app/data/user/.runtime/remotion. edge-tts is bundled so narration and read-aloud work offline-ish with no API key.
• Notebooks replace Co-Writer's editor with pages, subpages and blocks; Word import/export and Favorites-backed source records are included.
• Learning/RAG adds pageindex, bm25s, the LlamaIndex stack and faiss-cpu (1.12+ on Python 3.14). Interrupted rebuilds resume completed embedding checkpoints.
• Upgrade note. Existing data under /app/data is untouched by the version change; only the installed Python/Node artifacts change.

v1.6.14

• Watching moves into Reading. Video learning now lives under Reading, and existing Watching conversations are migrated automatically when reopened — no action required, and all data stays under /app/data.
• Providers. Opper (LLM and embedding) and Y-API (LLM) join the provider catalog, and GitHub Copilot signs in per account via deeptutor provider login github-copilot.
• Managed plugins. Plugins run in isolated virtualenvs created under /app/data; they install only after explicit permission approval and need an app restart when a plugin generation changes. The shipped catalog is empty, so nothing installs automatically.
• Knowledge bases. Answers can cite original figures, tables and PDF pages; older indexes must be re-parsed and reindexed to gain figure records.

Package Layout

• Dockerfile — multi-stage build. Fetches the upstream source tarball, builds the Next.js frontend from source (standalone output) and installs Python dependencies into a venv. Build stages use the approved Cloudron images cloudron/node-base:24 and tcmbp132021/cloudron-minibase; the final runtime stage is tcmbp132021/cloudron-minibase:ubuntu26.04 (Ubuntu 26.04, Python 3.14) with Node 24 copied in from cloudron/node-base:24.
• CloudronManifest.json — app metadata, 8 GB memory limit, port 3782 (Next.js frontend), Localstorage addon (/app/data).
• start.sh — entrypoint: creates dirs, copies default JSON settings, injects CLOUDRON_APP_ORIGIN into CORS origins, exports runtime env from settings, launches supervisord.
• start-backend.sh / start-frontend.sh — per-program launchers for uvicorn and the Next.js standalone server.
• supervisor/ — supervisord daemon + programs config (runs backend and frontend as user cloudron).
• defaults/settings/ — deployment overrides copied into /app/data/user/settings/ on first run: system.json, auth.json, and document_parsing.json (which selects the bundled MarkItDown engine). All other settings files (main.yaml, agents.yaml, interface.json, model_catalog.json, integrations.json, …) are seeded by upstream on first start.

Multi-user

DeepTutor's optional multi-user layer is included in this build but disabled by default (defaults/settings/auth.json → "enabled": false). With it off the app is single-user: no login, every request runs as the local admin, and data lives under /app/data/user.

To enable it:

1. Edit data/user/settings/auth.json (Cloudron File Manager → app data, or the app's web terminal) and set "enabled": true. Leave username/password_hash empty to bootstrap through registration, or set both to pin a fixed admin account (bcrypt hash) and close self-registration.
2. Restart the app — auth is read at process start, so the change does not apply until restart.
3. Open /register; the first user to register becomes admin. Add further accounts from /admin/users.

Once enabled, each account gets an isolated workspace under /app/data/users/<uid>/, with accounts, grants and audit data under /app/data/system/. Admins assign per-user access to knowledge bases, books, skills, models, partners, tools and learning surfaces; roles are admin, teacher, student and user, and learner accounts add guardian controls, device credentials and learning policy. The shipped cookie_secure: true is correct for Cloudron's HTTPS front end.

Notes:

• Everything remains under /app/data and is covered by Cloudron backups.
• /healthz.txt is exempt from the auth gate, so enabling login does not affect Cloudron's health checks.
• This package does not use Cloudron's proxyAuth SSO addon — accounts are managed inside DeepTutor.
• Leave integrations.pocketbase_url blank for multi-user; PocketBase mode is single-user only.

Document parsing (knowledge-base ingestion)

• MarkItDown [all] is installed and set as the default parsing engine (document_parsing.json → "engine": "markitdown"). It gives the broadest local coverage of the optional engines: PDF, modern and legacy Office, e-mail (.msg), audio (.mp3/.m4a/.wav/.mp4), images, notebooks, feeds, archives and text — with no runtime model download.
• The built-in text_only engine remains available and is the automatic fallback for formats the active engine does not declare.
• Apache Tika is supported but not bundled — it is remote-only. Run a Tika 4.x server yourself and set its URL under Settings → Document Parsing (see below).
• Not installed (selectable only after adding them): pymupdf4llm, docling, liteparse, and local MinerU. MinerU can instead be used in cloud mode with just an API token (no package change).
• Only one engine is active at a time (global setting); installing several does not combine them.
• Optional image-description model — an independent vision model can be selected under Settings → Document Parsing to describe document figures and images (useful when the main model cannot inspect images). Older indexed content must be re-parsed and reindexed to gain newly generated descriptions.

The in-app "one-click install" buttons for the other engines are not reliable on Cloudron — /app/code is read-only and a runtime pip install into /venv is lost on the next restart/update. Add engines in the Dockerfile's python-builder stage instead.

Self-hosting Apache Tika

DeepTutor's Tika adapter talks to a Tika 4.0.0 or newer server over its REST API:

• PUT /tika with the file body (Content-Type: application/octet-stream, Content-Disposition filename). Tika 4 returns Markdown from the bare /tika endpoint.
• GET /version for the Settings "Test connection" button (version must be >= 4.0.0).
• No authentication header is sent, so the server must be reachable without auth (or front it with a proxy that permits the app). Requests can take up to 5 minutes.

Run the official image (the -full variant includes the most parsers, e.g. OCR):

docker run -d --name tika -p 9998:9998 apache/tika:latest-full

Ensure the DeepTutor container can reach that URL (same host/network or a public address), then enter it under Settings → Document Parsing → Tika (default http://localhost:9998).

Not packaged / not deployed

This package installs upstream's requirements/full.txt (the v1.7.x "Full app" module profile, which chains requirements/modules/*.txt from core.txt) plus MarkItDown [all] and edge-tts, plus what tcmbp132021/cloudron-minibase already provides plus git, ne, Node 24 and the OpenCV/document-parsing shared libraries. The following upstream optional extras and system components are intentionally not included (minimal-footprint policy). The core app runs without them; the affected feature reports itself unavailable or falls back.

Not included	Effect
Matrix (Element) channel SDK (requirements/matrix.txt)	The Matrix channel is unavailable; the other partner/IM channels (Telegram, WeCom, Feishu/Lark, DingTalk, Slack, QQ, Zulip, MS Teams, OneBot) are included
manim + LaTeX runtime (deeptutor-renderer-manim)	Math Animator unavailable
GraphRAG pipeline (graphrag, Python < 3.14 only)	The GraphRAG knowledge-base pipeline is unavailable; the bundled LlamaIndex + PageIndex + BM25 pipelines cover indexing and retrieval
LibreOffice + Noto CJK / Liberation fonts	Office previews fall back to in-browser renderers (DOCX/XLSX) or extracted text
ffmpeg	No native DashScope/Volcengine transcription of browser WebM/Opus recordings (also needed by Manim encoding)
sentence-transformers / torch (rag-rerank)	Re-ranking unavailable
Extra parsing engines pymupdf4llm, docling, liteparse, local MinerU; Tika server	MarkItDown (bundled) + built-in text_only cover most formats; Tika works once you point it at a self-hosted server
codebuddy-agent-sdk (codebuddy)	CodeBuddy in-app login unavailable
fastapi-guard (guard extra)	Optional request screening (rate limit, IP allow/deny, attack-pattern scan) unavailable; off by default upstream and in this package
External sandbox-runner sidecar / bubblewrap hardening	In-container restricted-subprocess execution only
PocketBase and Redis server sidecars	Not used; single-worker, in-memory coordination (redis SDK is installed but no server)
Codex OAuth loopback ports 1455/1457	Codex must be configured via API key (see POSTINSTALL.md)

There is no runtime toggle to add these: upstream's DEEPTUTOR_EXTRAS / DEEPTUTOR_APT_PACKAGES entrypoint mechanism is not used, because this package launches the backend directly via supervisord. Enabling any of the above requires editing the Dockerfile (add the Python extra in the python-builder stage and/or the system package in the production stage) and rebuilding.

---

Packaged by @timconsidine https://communityapps.appx.uk (full portfolio: https://myca.appx.uk)