Getting Started

Get Joidy up and running in minutes with Docker Compose.

Getting Started

Welcome to Joidy! This guide will help you get up and running quickly.

What You'll Need

Docker & Docker Compose
4GB+ RAM
(Optional) An AI API key (Gemini, OpenAI, etc.)

1. Install

Choose one method:

Docker (easiest):

git clone https://github.com/Axel-DaMage/joidy.git
cd joidy
cp .env.example .env
docker compose up -d

One-liner (Linux/macOS):

curl -fsSL https://raw.githubusercontent.com/Axel-DaMage/joidy/main/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/Axel-DaMage/joidy/main/scripts/install.ps1 | iex

Homebrew:

brew tap Axel-DaMage/homebrew-tap
brew install joidy
joidy up

AUR:

yay -S joidy

2. Configure

Edit .env with your settings:

vim .env

At minimum, set SECRET_KEY (openssl rand -hex 32), OBSIDIAN_VAULT_PATH, and GEMINI_API_KEY (or another AI provider key — Ollama needs none). If you plan to run with APP_ENV=production, also set AUTH_PASSWORD.

3. Verify

Open http://localhost:3000 — you should see the Joidy dashboard.

Check service health:

docker compose ps
curl http://localhost:8000/health

4. Configure Obsidian (Optional)

Add your vault path to .env (~ is expanded to your home directory):

OBSIDIAN_VAULT_PATH=~/Documents/obsidian/my-vault

Restart the worker:

docker compose restart worker

5. Enable AI Features (Optional)

Add API keys to .env:

GEMINI_API_KEY=your-key
# or
OPENAI_API_KEY=your-key

6. Create Your First Note

Open http://localhost:3000
Click "New Note" or create a .md file in your Obsidian vault
Watch your plant grow and XP increase!

Next Steps

Configuration - Full configuration reference
Architecture - How it works under the hood
API Reference - Integrate with Joidy
GitHub Issues - Report bugs
Discussions - Ask questions

Troubleshooting

Services Won't Start

# Check logs
docker compose logs -f

Port conflicts: joidy up automatically tries subsequent ports. With plain docker compose, override FRONTEND_PORT, API_PORT, AI_SERVICE_PORT, or WORKER_PORT in .env.

Permission Issues

# Fix data directory permissions
sudo chown -R 1000:1000 ./data

Database Errors

# Reset database (loses all data!)
docker compose down -v
docker compose up -d