Quick Start · Setup Guide · + Architecture · + Security · Contributing · Roadmap
@@ -51,15 +55,15 @@ Native installs, GPU notes, Windows/macOS instructions, HTTPS, and configuration ## Demo -A full hover-to-play tour lives on the landing page: [`docs/index.html`](docs/index.html). +Explore the interface through the [interactive product tour](docs/index.html). ## Contributing -Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, documentation, and small focused refactors. See [CONTRIBUTING.md](CONTRIBUTING.md), the [public roadmap](ROADMAP.md), and the open [GitHub issues](https://github.com/odysseus-dev/odysseus/issues). +Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, documentation, and small focused refactors. Read the [contributing guide](CONTRIBUTING.md), review the [public roadmap](ROADMAP.md), and browse the open [GitHub issues](https://github.com/odysseus-dev/odysseus/issues). ## Security -Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled, keep private data out of Git, and do not expose raw model/service ports publicly. Deployment details are in the [setup guide](docs/setup.md#security-notes). +Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled, keep private data out of Git, and do not expose raw model or service ports publicly. Read the [security policy](SECURITY.md) and the [deployment security guidance](docs/setup.md#security-notes). ## Star History @@ -73,4 +77,4 @@ Odysseus is a self-hosted workspace with powerful local tools. Keep auth enabled ## License -AGPL-3.0-or-later -- see [LICENSE](LICENSE) and [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md). +Licensed under AGPL-3.0-or-later. See the [license](LICENSE) and [acknowledgments](ACKNOWLEDGMENTS.md). diff --git a/docs/setup.md b/docs/setup.md index 61381461b..ab7265698 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,6 +1,28 @@ # Odysseus Setup Guide -This page keeps the detailed install, deployment, troubleshooting, and configuration notes out of the front README. +This guide covers installation, deployment, troubleshooting, and configuration. +For a minimal Docker installation, start with the +[repository README](../README.md#quick-start). + +## On this page + +- [Quick Start](#quick-start) + - [Docker](#docker-recommended) + - [Native Linux and macOS](#native-linux--macos) + - [Apple Silicon](#apple-silicon) + - [Native Windows](#native-windows) +- [Troubleshooting and advanced setup](#troubleshooting--advanced-setup) +- [Security notes](#security-notes) +- [Configuration](#configuration) +- [Architecture](#architecture) +- [Data and backups](#data) + +Related guidance: + +- [Security policy](../SECURITY.md) +- [Architecture overview](ARCHITECTURE.md) +- [Backup and restore guide](backup-restore.md) +- [Contributing guide](../CONTRIBUTING.md) ## Quick Start @@ -15,8 +37,8 @@ On first setup, Odysseus creates an admin account (`admin` unless For Docker installs, the same line is in `docker compose logs odysseus`. Use that for the first login, then change it in **Settings**. -Contributing? See [CONTRIBUTING.md](../CONTRIBUTING.md) for setup, testing, and -pull request guidelines. +Contributing? See the [contributing guide](../CONTRIBUTING.md) for development +setup, testing, and pull request guidelines. ### Docker (recommended) ```bash @@ -441,8 +463,8 @@ uv pip sync requirements.lock # reproduce it exactly la ### Outlook / Office 365 email Odysseus email accounts currently use IMAP/SMTP username-password auth. Outlook and Microsoft 365 generally require OAuth instead, so normal Microsoft mailbox -passwords will fail. See [email-outlook.md](email-outlook.md) for the -current limitation and the planned integration direction. +passwords will fail. See the [Outlook and Microsoft 365 email guide](email-outlook.md) +for the current limitation and planned integration direction. ## Security Notes Odysseus is a self-hosted workspace with powerful local tools: shell access, file uploads, model downloads, web research, email/calendar integrations, and API tokens. Treat it like an admin console. @@ -530,19 +552,16 @@ npx -y @playwright/mcp@latest --version That installs `@playwright/mcp` plus Playwright (~300MB total). Restart Odysseus and the server will register at startup. ## Architecture -``` -app.py # FastAPI entry point -core/ auth, database, middleware, constants -src/ llm_core, agent_loop, agent_tools, chat_processor, search/ -routes/ chat, session, document, memory, model … endpoints -services/ docs, memory, search, hwfit (Cookbook) … -static/ index.html + app.js + style.css + js/ (modular front-end) -docs/ landing page (index.html) + preview clips -``` + +For stable high-level runtime structure, subsystem boundaries, and documentation +authority, see the [architecture overview](ARCHITECTURE.md). + +Source code, tests, and configuration remain authoritative for +implementation-sensitive behaviour. ## Data All user data lives in `data/` (gitignored): `app.db` (sessions, messages, documents), `memory.json`, `presets.json`, `uploads/`, `personal_docs/`, `chroma/`, `settings.json`. -To back up or restore everything in `data/`, see the -[Backup & Restore guide](backup-restore.md). +To protect or recover this data, follow the +[backup and restore guide](backup-restore.md).