Skip to content

DATA_STORAGE.md

Latest commit

 

History

History
93 lines (74 loc) · 4.48 KB

DATA_STORAGE.md

File metadata and controls

93 lines (74 loc) · 4.48 KB
Raw

Local Data Persistence

Handbook · Workspaces · Containers

DeepTutor's default installation does not require PostgreSQL, MySQL, or another database server. Durable state is written below one runtime-home directory, so a deployment has one tree to mount, inspect, and back up. Some state is stored in SQLite, while settings, generated artifacts, knowledge-base indexes, caches, and imported source files remain ordinary files.

Where Data Lives

The runtime home is the directory from which you start DeepTutor. Set DEEPTUTOR_HOME or pass deeptutor start --home / deeptutor init --home to choose another directory. In the published container, the same tree is mounted at /app/data.

The default admin scope uses this layout:

Path Contents
data/user/settings/ JSON/YAML settings and provider credentials
data/user/chat_history.db SQLite sessions, messages, turns, question-bank entries, and practice data
data/user/.runtime/ Private runtime state such as workspaces.sqlite3
data/user/workspace/ Default Content Workspace and generated artifacts
data/user/workspace/notebook/ Favorite collections and their index as JSON files (legacy directory name)
data/user/workspace/co-writer/documents/doc_<id>/manifest.json Authored note pages, blocks, revisions, and page metadata
data/user/logs/ Application logs
data/knowledge_bases/ Knowledge-base indexes and versioned source data
data/parse_cache/ Shared document-parse cache
data/users/<user-id>/ Per-user workspace roots when local multi-user auth is enabled
data/partners/<partner-id>/ Synthetic Partner workspaces
data/system/ Accounts, grants, audit records, indexes, and owner credentials

A selected Content Workspace can be outside data/user. In that case its private learning state is under <workspace>/.deeptutor/data/, while account settings, credentials, Memory, and workspace registrations remain in the runtime home. Run deeptutor workspace show to print the selected workspace path.

Favorites and authored notes are separate stores. The legacy notebook_entries SQLite table holds question-bank entries; it is not the storage for authored note blocks or favorite collections. In a selected external workspace, those file-based stores live under its private .deeptutor/data/workspace/ tree, using the same notebook/ and co-writer/documents/ subdirectories. Back up the full workspace, including hidden .deeptutor files, to preserve both the learning records and the note/favorite content.

Database Support

SQLite is the supported local backend. There is no supported PostgreSQL or MySQL connection setting; setting DATABASE_URL or a similar environment variable does not redirect DeepTutor storage.

PocketBase is an optional integration configured through data/user/settings/integrations.json. It stores supported session collections in PocketBase, but it is not a PostgreSQL adapter and does not move all runtime state into PocketBase. Settings, credentials, knowledge-base indexes, parse caches, logs, and workspace artifacts remain in the runtime tree. Current PocketBase mode is single-user; leave integrations.pocketbase_url blank for the supported local multi-user JSON/SQLite layout.

Inspecting and Backing Up State

From your runtime home, after DeepTutor has created data, list the SQLite databases in the private runtime tree:

find data -type f \( -name '*.db' -o -name '*.sqlite3' \) -print

For a selected external Content Workspace, inspect its private database files:

workspace="$(deeptutor workspace show | sed -n 's/^Path: //p')"
if [ -d "$workspace/.deeptutor/data" ]; then
  find "$workspace/.deeptutor/data" -type f \
    \( -name '*.db' -o -name '*.sqlite3' \) -print
fi

Stop DeepTutor and any Partner processes before copying data or a workspace. SQLite may have live write-ahead log files, so copying only .db files while the app runs can lose recent transactions. Back up the complete runtime-home data directory plus each separately configured Content Workspace. Treat every copy as sensitive because it can contain credentials, private conversation text, and uploaded learning material.

Implementation and verification