126 lines
3.6 KiB
Markdown
Executable File
126 lines
3.6 KiB
Markdown
Executable File
# AdventureOS
|
|
|
|
A self-hosted personal companion for building consistency, learning, discipline, and growth — styled as a nostalgic personal operating system and adventure game.
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 22+
|
|
- PostgreSQL running on `localhost:5432`
|
|
- Docker & Docker Compose (for the app and Ollama)
|
|
|
|
### Development
|
|
|
|
```bash
|
|
# Start Ollama
|
|
docker compose up ollama -d
|
|
|
|
# Copy environment
|
|
cp .env.example .env
|
|
|
|
# Create the PostgreSQL role/database if needed
|
|
sudo -u postgres psql -c "CREATE ROLE adventureos WITH LOGIN PASSWORD 'adventureos';"
|
|
sudo -u postgres createdb -O adventureos adventureos
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run migrations and seed
|
|
npm run db:generate
|
|
npm run db:migrate
|
|
npm run db:seed
|
|
|
|
# Start dev server
|
|
npm run dev
|
|
```
|
|
|
|
Open http://localhost:3000 — default password: `adventure` (set `AUTH_PASSWORD` in `.env`).
|
|
|
|
Docker production serves the app at http://localhost:3060.
|
|
|
|
### Production (Docker)
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
### Cron Jobs
|
|
|
|
Schedule these on your server (daily/weekly):
|
|
|
|
```bash
|
|
# Materialize today's adventure (midnight)
|
|
curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=materialize"
|
|
|
|
# Generate daily quests (6am)
|
|
curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=generate-quests"
|
|
|
|
# Generate weekly explorations (Monday 6am)
|
|
curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=generate-explorations"
|
|
|
|
# Generate weekly review (Sunday 6pm)
|
|
curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=generate-weekly-review"
|
|
|
|
# Prune action history older than 90 days (weekly)
|
|
curl -X POST -H "x-cron-secret: YOUR_CRON_SECRET" "http://localhost:3060/api/cron?action=prune-actions"
|
|
```
|
|
|
|
### Ollama Models
|
|
|
|
```bash
|
|
docker compose exec ollama ollama pull llama3.2:3b
|
|
docker compose exec ollama ollama pull llama3.1:8b
|
|
```
|
|
|
|
### Themes, Undo & AI Settings
|
|
|
|
- **Themes:** Settings → Appearance — 11 nostalgia themes with live preview. Default for new installs: `minimal-dark`. Legacy `xp` maps to `windows-xp-light`.
|
|
- **Undo:** After adventure/reading actions, use the toast Undo button or Settings → Action History.
|
|
- **AI:** Settings → AI Configuration, AI Templates, System Prompts, AI Health. Provider keys stay in `.env` only (`OPENAI_API_KEY`, `LLAMACPP_API_KEY`).
|
|
- **Memories:** See [How Memories Work](docs/MEMORIES.md) for the phrases and review flow the mentor understands.
|
|
|
|
Run tests: `npm run test`
|
|
|
|
After upgrading, run migrations: `npm run db:migrate`
|
|
|
|
### Calibre Library (optional)
|
|
|
|
Connect a live Calibre library for the Library Wing — metadata is read read-only from `metadata.db`; reading progress is stored in Postgres.
|
|
|
|
```bash
|
|
# In .env
|
|
CALIBRE_LIBRARY_PATH=/path/to/Calibre Library
|
|
CALIBRE_READ_ONLY=true
|
|
```
|
|
|
|
For Docker, mount your library read-only (see `docker-compose.yml`):
|
|
|
|
```yaml
|
|
volumes:
|
|
- /path/to/Calibre Library:/calibre-library:ro
|
|
environment:
|
|
CALIBRE_LIBRARY_PATH: /calibre-library
|
|
```
|
|
|
|
If Calibre is open and locks the database, the Library page shows a friendly retry message. Without Calibre configured, manual book entry still works.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
nostalgia/
|
|
├── apps/web/ # Next.js 15 application
|
|
├── packages/db/ # Drizzle schema + migrations
|
|
├── packages/shared/ # XP formulas, scores, types
|
|
├── docker-compose.yml
|
|
├── scripts/backup.sh
|
|
└── docs/
|
|
```
|
|
|
|
## Philosophy
|
|
|
|
- Consistency over productivity
|
|
- No guilt, no streak destruction
|
|
- The user *is* the character
|
|
- Local AI on your server — data never leaves your infrastructure
|