Personal knowledge management system with gamification. Manage notes, goals, streaks, and skills through a web dashboard with AI-powered features.
Installation
Prerequisito: Docker (incluye Docker Compose).
Linux / macOS
curl -fsSL https://raw.githubusercontent.com/Axel-DaMage/joidy/development/scripts/install.sh | bash
Clona el repo, genera secretos automáticamente e instala el comando joidy. Luego:
joidy up # Inicia todos los servicios
# Abre http://localhost:3000
Windows
Docker Desktop en Windows requiere WSL2. El camino más simple:
# 1. Instala WSL2 con Ubuntu (como Administrador, una sola vez):
wsl --install
# 2. Reinicia y abre Ubuntu desde el menú de inicio, luego pega:
# curl -fsSL https://raw.githubusercontent.com/Axel-DaMage/joidy/development/scripts/install.sh | bash
PowerShell nativo (sin WSL2): irm https://raw.githubusercontent.com/Axel-DaMage/joidy/development/scripts/install.ps1 | iex
Otros métodos
# Homebrew
brew tap Axel-DaMage/homebrew-tap && brew install joidy
# AUR (Arch Linux)
yay -S joidy
# Manual
git clone https://github.com/Axel-DaMage/joidy.git && cd joidy && cp .env.example .env && docker compose up -d
→ Guía completa de instalación: INSTALL.md
Requirements
- Docker + Docker Compose
- Windows: WSL2 (
wsl --install) — necesario para Docker Desktop
→ Ver INSTALL.md para instrucciones detalladas por plataforma.
Configuration
Edit .env after cloning:
| Variable | Description | Source |
|---|
GEMINI_API_KEY | AI service key | Google AI Studio |
OBSIDIAN_VAULT_PATH | Path to your Obsidian vault | e.g. /home/user/Documents/Obsidian |
OBSIDIAN_WEBHOOK_SECRET | Shared secret for Obsidian webhook auth | Optional, any random string |
SECRET_KEY | Session signing key | Auto-generated on first setup |
Optional:
GITHUB_TOKEN= # GitHub sync
GITHUB_USERNAME=
TELEGRAM_BOT_TOKEN= # Notifications
TELEGRAM_ALLOWED_USER_ID=
Usage
Development
make dev # Hot reload, source mounts
make stop # Stop all services
make logs # View logs
make test # Run tests
make migrate # Database migrations
Power saving: idle watchdog
On battery- or thermally-constrained machines the stack can put itself to
sleep when nobody is using it:
joidy idle enable # start the background watcher
joidy idle status # watcher state, last activity, countdown to sleep
joidy idle disable # stop the watcher (services untouched)
joidy wake # restore the services that were running before sleep
The watcher polls established HTTP connections on the published ports
(frontend/api/ai-service/worker), active PostgreSQL sessions, and file
changes under the vault. After JOIDY_IDLE_TIMEOUT minutes in .env
(default 15) with no activity it runs the existing joidy sleep path and
additionally stops the frontend — the heaviest idle CPU consumer. Postgres
keeps running for data safety; opt into hibernating it with
joidy idle enable --idle-hibernate-db. New activity while asleep restores
the recorded services automatically.
An optional systemd user unit keeps the watcher alive across logouts:
scripts/joidy-idle-watchdog.service (install notes inside the file).
Database Backups
joidy up starts a backup sidecar that automatically takes compressed
pg_dump -Fc snapshots — no user action required. Dumps are written to
data/backups/ (on the host, outside the postgres_data volume) with
timestamped filenames and retention pruning. Set BACKUP_ENABLED=false in
.env to opt out; make dev and plain docker compose up never start the
sidecar (manual: docker compose --profile backup up -d backup).
| Variable | Default | Description |
|---|
BACKUP_SCHEDULE | 0 3 * * * | Cron expression (or @daily, @hourly, @weekly, @monthly); evaluated in USER_TIMEZONE |
BACKUP_RETENTION_DAYS | 14 | Keep every dump for this many days |
BACKUP_RETENTION_WEEKS | 4 | Additionally keep Sunday dumps (BACKUP_WEEKLY_DAY) for this many weeks |
JOIDY_BACKUP_DIR | <data>/backups | Host directory for dumps |
joidy backup # manual dump
joidy restore data/backups/joidy-YYYYMMDD-HHMMSS.dump # restore (refuses on a live DB)
joidy restore <file> --force # overwrite a live DB
make db-backup / make db-restore FILE=<dump> # same via make
make backup-verify # round-trip test: dump → restore to a throwaway DB → health check
Obsidian Webhook Sync
Joidy supports bidirectional sync with Obsidian. In addition to the local
file watcher (worker), you can configure Obsidian to push changes via webhook
for instant sync without polling.
Setup
- Set
OBSIDIAN_WEBHOOK_SECRET in .env to a random string
- Configure an Obsidian plugin (e.g. Obsidian Webhook) to send events to:
POST http://localhost:8000/webhook/obsidian?secret=YOUR_SECRET
Payload format
{
"event": "create",
"path": "/vault/My Note.md",
"content": "---\ntitle: My Note\ntags: [python, web]\n---\n# Content here",
"mtime": 1700000000
}
| Field | Type | Required | Description |
|---|
event | string | yes | create, update, or delete |
path | string | yes | File path (matches source_path in DB) |
content | string | create/update | Full file content (frontmatter + body) |
mtime | int | no | Remote modification time (Unix timestamp) |
Events
- create: Creates a new note in the DB. Extracts title from frontmatter or filename, tags from frontmatter + inline
#tags.
- update: Updates existing note by
source_path. If not found, creates it instead.
- delete: Deletes the note matching
source_path. No-op if not found.
Authentication
- If
OBSIDIAN_WEBHOOK_SECRET is set: requests must include ?secret=<secret> query param
- If not set but
AUTH_PASSWORD is configured: JWT auth required
- If neither is set (dev mode): no auth required
Legacy endpoint
POST /webhook/obsidian/legacy — accepts the old payload format (note_id, path, remote_mtime) for backward compatibility. Only records sync state without processing content.
Architecture
.
├── api/ FastAPI REST backend
├── ai-service/ AI service (Gemini, OpenAI, etc.)
├── worker/ Background tasks (Obsidian sync, daily summaries)
├── frontend/ SvelteKit web application
├── data/ Database, uploads, vault
├── docker-compose.yml
└── Makefile
graph LR
User[Usuario / Navegador]
FE[Frontend 3000<br/>SvelteKit]
API[API 8000<br/>FastAPI]
AI[AI 8002<br/>FastAPI]
Worker[Worker 8001<br/>asyncio]
DB[(PostgreSQL 16 + pgvector)]
Vault[Obsidian Vault]
User --> FE
FE --> API
API --> DB
API --> AI
API --> Worker
Worker --> Vault
Worker --> API
Quick Start
See QUICKSTART.md for a step-by-step dev onboarding guide.
Documentation
License
GNU General Public License v3.0. See LICENSE.
