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):

docker compose up -d

One-liner:

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

Homebrew:

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

AUR:

yay -S joidy

Manual:

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

2. Configure

Edit .env with your settings:

vim .env

At minimum, set GEMINI_API_KEY (or another AI provider key) and SECRET_KEY.

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:

OBSIDIAN_VAULT_PATH=/home/user/obsidian-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

1. Open http://localhost:3000
2. Click "New Note" or create a .md file in your Obsidian vault
3. 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

# Common: port conflicts
# Change ports in docker-compose.yml

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