{"id":51104084,"url":"https://github.com/hiai-gg/hiai-docs","last_synced_at":"2026-06-24T13:00:49.668Z","repository":{"id":366016513,"uuid":"1249550690","full_name":"HiAi-gg/hiai-docs","owner":"HiAi-gg","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-19T22:42:54.000Z","size":612,"stargazers_count":0,"open_issues_count":6,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T23:12:18.751Z","etag":null,"topics":["ai-embeddings","bun","docker","documentation","knowledge-base","markdown","ollama","open-source","pgvector","rag","self-hosted","semantic-search","sveltekit","tiptap","typescript","wiki"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HiAi-gg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["hiai-dev"]}},"created_at":"2026-05-25T20:27:10.000Z","updated_at":"2026-06-19T22:42:58.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/HiAi-gg/hiai-docs","commit_stats":null,"previous_names":["hiai-gg/hiai-docs"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/HiAi-gg/hiai-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HiAi-gg%2Fhiai-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HiAi-gg%2Fhiai-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HiAi-gg%2Fhiai-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HiAi-gg%2Fhiai-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HiAi-gg","download_url":"https://codeload.github.com/HiAi-gg/hiai-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HiAi-gg%2Fhiai-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34733256,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-embeddings","bun","docker","documentation","knowledge-base","markdown","ollama","open-source","pgvector","rag","self-hosted","semantic-search","sveltekit","tiptap","typescript","wiki"],"created_at":"2026-06-24T13:00:48.671Z","updated_at":"2026-06-24T13:00:49.662Z","avatar_url":"https://github.com/HiAi-gg.png","language":"TypeScript","funding_links":["https://github.com/sponsors/hiai-dev"],"categories":[],"sub_categories":[],"readme":"# hiai-docs\n\n**The lightest AI-native self-hosted knowledge vault.**\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/hiai-gg/hiai-docs?sort=semver)](https://github.com/hiai-gg/hiai-docs/releases)\n[![Stars](https://img.shields.io/github/stars/hiai-gg/hiai-docs)](https://github.com/hiai-gg/hiai-docs/stargazers)\n[![CI](https://github.com/hiai-gg/hiai-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/hiai-gg/hiai-docs/actions/workflows/ci.yml)\n[![Bun](https://img.shields.io/badge/Runtime-Bun_1.3-black?logo=bun\u0026logoColor=white)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org)\n[![Svelte](https://img.shields.io/badge/Svelte-5.x-FF3E00?logo=svelte\u0026logoColor=white)](https://svelte.dev)\n[![Elysia](https://img.shields.io/badge/Elysia-1.4-lightgrey?logo=elysia\u0026logoColor=white)](https://elysiajs.com)\n[![Tailwind_CSS](https://img.shields.io/badge/Tailwind_CSS-v4-06B6D4?logo=tailwindcss\u0026logoColor=white)](https://tailwindcss.com)\n[![Drizzle_ORM](https://img.shields.io/badge/Drizzle_ORM-0.45-C5F74F?logo=drizzle\u0026logoColor=black)](https://orm.drizzle.team)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\nhiai-docs is a lightweight **self-hosted knowledge base** built for users who want speed, full data ownership, and strong AI capabilities without heavy enterprise overhead. \n\nIf you are looking for a **local LLM knowledge base** or a **lightweight Outline alternative** / **Docmost alternative**, hiai-docs offers an elegant, **RAG-ready knowledge vault** that automatically generates vector embeddings on every save, supports hybrid semantic search, and provides a clean REST API for AI agent integration.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Screenshots](#screenshots)\n- [Quick Start](#quick-start)\n- [Stack](#stack)\n- [Comparison](#comparison)\n- [Project Structure](#project-structure)\n- [Configuration](#configuration)\n- [API Documentation](#api-documentation)\n- [Contributing](#contributing)\n- [License](#license)\n- [Related Projects](#related-projects)\n\n---\n\n\u003cimg width=\"1920\" height=\"974\" alt=\"docs\" src=\"https://github.com/user-attachments/assets/94701d01-a361-4ca1-b16d-de2a0c64d684\" /\u003e\n\n\n## Features\n\n- **Rich WYSIWYG editor** — powerful visual editing with TipTap v3 + svelte-tiptap\n- **AI-native** — automatic chunking + vector embeddings on every save\n- **Semantic search** — hybrid full-text + pgvector search\n- **Folder hierarchy** — nested folders to organize your documents\n- **Sharing** — token-protected links with password, expiration, and guest access\n- **Import / Export** — support for Markdown (.md) files\n- **Agent-ready** — clean REST API for AI agents (Mastra compatible and others)\n- **Self-hosted** — full data ownership with minimal resource usage\n\n## Screenshots\n\u003cimg width=\"999\" height=\"594\" alt=\"docs_screenshot\" src=\"https://github.com/user-attachments/assets/1ba409e7-32cf-40d3-ae30-f8369e48cb53\" /\u003e\n\n---\n\n## Quick Start\n\n### Docker (Production-style)\n\n```bash\ngit clone https://github.com/hiai-gg/hiai-docs.git\ncd hiai-docs\ncp .env.example .env\n# Edit .env with your settings\n\ndocker compose up -d\n```\n\nOpen http://localhost:50701\n\n## Agentic Quickstart (AI-Powered Setup)\n\nDon't want to run setup commands manually? Copy-paste this unified prompt into your AI assistant (OpenCode, Claude Code, Cursor, Copilot, etc.) and let it do the work:\n\n```text\nSet up and launch the hiai-docs project on my local system:\n1. Clone the repository at https://github.com/hiai-gg/hiai-docs (if not already cloned)\n2. Copy .env.example to .env\n3. Generate a secure random auth secret using openssl or a secure generator, and set it as BETTER_AUTH_SECRET in .env\n4. Install all dependencies with \"bun install\"\n5. Boot up the developer Docker container dependencies (Postgres, Redis, MinIO) by running:\n    bun run docker:dev\n6. Generate and apply database migrations to setup schemas by running:\n   bun run db:push\n7. Spin up the application services (Elysia API and SvelteKit web) in development/watch mode:\n   bun run dev\n8. Verify health status by checking:\n   - SvelteKit Web UI: http://localhost:50701\n   - Elysia API Health: http://localhost:50700/api/health\n```\n\n### Local Development (Recommended for hacking)\n\nTwo equivalent workflows — pick one. Both give you live-reload at http://localhost:50701.\n\n#### Option A — Hybrid (infra in Docker, api+web on host)\n\nThis is the fastest dev loop. `bun run dev` runs `vite dev` (port 50701) and `bun --watch` for the api in parallel; both auto-reload on file changes.\n\n```bash\n# 1. Install JS deps once\nbun install\n\n# 2. Start infrastructure in Docker\nbun run docker:dev          # brings up postgres, redis, minio\n\n# 3. Push DB schema (one-time, or after schema changes)\nbun run db:push\n\n# 4. Start api + web on the host, with live reload\nbun run dev\n# vite dev → http://localhost:50701\n# api      → http://localhost:50700\n```\n\nStop the infra when done: `bun run stop`\n\n#### Option B — Full Docker with live-reload bind mounts\n\n`docker-compose.dev.yml` mounts the source into the api/web containers, so editing a file on the host is picked up inside the container (vite HMR + bun --watch). Useful when you want everything isolated in Docker.\n\n```bash\nbun run docker:dev\n# Open http://localhost:50701\n```\n\n\u003e The `web` and `api` services in `docker-compose.dev.yml` bind `./:/app`, so any edit on the host is reflected inside the container without rebuilding.\n\n### Why is port 50701 special?\n\nThe frontend dev server is pinned to port 50701 in `frontend/vite.config.ts` with `strictPort: true`. That last flag is important: if 50701 is already taken (e.g. a stale container from a previous run), vite will **fail loudly** instead of silently falling back to 5173 — which would leave you staring at an old build at http://localhost:50701. If you see \"port 50701 in use\", run `docker compose down` (or `bun run stop`) and retry.\n\n### Troubleshooting\n\n#### Docker: permission denied\n\nIf you get `permission denied` when running Docker commands:\n\n```bash\n# Add your user to the docker group\nsudo usermod -aG docker $USER\n\n# Log out and back in, or run:\nnewgrp docker\n```\n\nThen verify: `docker ps` should work without `sudo`.\n\n- **Port 50701 already in use** — `docker compose down` to stop stale containers, then retry `bun run dev` or `bun run docker:dev`.\n- **Changes not showing up** — `bun run dev` already wires HMR. If running via Docker, confirm the bind mount is in `docker-compose.dev.yml` (not the prod `docker-compose.yml`, which builds an immutable image).\n- **`bun install` complains about the lockfile** — ensure `bun.lock` is in sync: `bun install`.\n- **Docker `web` build works without paraglide patches** — As of `@inlang/paraglide-js@2.x`, the `@inlang/sdk@2.x` rewrite no longer emits the `data:` URLs that triggered Bun's `NameTooLong` error. The old `sed` patch on `frontend/Dockerfile` was removed. i18n is now driven by `@inlang/paraglide-js@2.x` directly (the SvelteKit adapter is deprecated) via `paraglideVitePlugin` in `vite.config.ts` and `paraglideMiddleware` in `src/hooks.server.ts`.\n\n---\n\n## Stack\n\n| Layer | Technology |\n|-------|----------|\n| Runtime | [Bun](https://bun.sh) 1.3.14+ |\n| Backend | [Elysia](https://elysiajs.com) 1.4.28+ |\n| ORM | [Drizzle ORM](https://orm.drizzle.team) 0.45.2+ |\n| Database | [PostgreSQL](https://postgresql.org) 18 + [pgvector](https://github.com/pgvector/pgvector) |\n| Cache | [Redis](https://redis.io) 8.6+ |\n| Auth | [Better Auth](https://better-auth.com) |\n| Frontend | [SvelteKit](https://kit.svelte.dev) 2.60+ |\n| UI | [shadcn-svelte](https://shadcn-svelte.com) (new-york style) |\n| Editor | [svelte-tiptap](https://github.com/sibiraj-s/svelte-tiptap) + [TipTap v3](https://tiptap.dev) |\n| Embeddings | OpenAI-compatible API (configurable) |\n| Storage | [MinIO](https://min.io) (S3-compatible) |\n\n---\n\n## Comparison with other self-hosted solutions\n\n| Project            | Best For                              | hiai-docs vs them                              | License / Limitations                          |\n|--------------------|---------------------------------------|------------------------------------------------|------------------------------------------------|\n| **La Suite Docs**  | Government \u0026 teams, strong block editor | Much lighter and faster                        | MIT (fully unrestricted)                       |\n| **Outline**        | Teams with integrations               | Lighter + built-in RAG out of the box          | BSL 1.1 – free for self-hosting, restrictions on offering as hosted service |\n| **Docmost**        | Confluence / Notion replacement       | Simpler, faster, lower resource usage          | AGPL-3.0 (Community) – fully open, Enterprise features extra |\n| **Wiki.js**        | Markdown + Git sync                   | Better AI \u0026 semantic search                    | AGPL-3.0                                       |\n| **hiai-docs**      | **Lightweight AI-first vault**        | —                                              | MIT (fully unrestricted)                       |\n| **AFFiNE**         | Notion + whiteboard experience        | Much lighter, far lower overhead               | MIT (frontend) + restrictive EE license (backend) – production limits (10 users / 100 GB on free tier) |\n| **Trilium Notes**  | Personal knowledge + scripting        | Better sharing \u0026 semantic search               | AGPL-3.0                                       |\n| **SilverBullet**   | Extensible Markdown notes             | Better AI integration \u0026 sharing                | MIT                                            |\n\n**hiai-docs** sits in the **lightweight AI-first** niche — ideal when you want built-in embeddings, fast performance, and minimal resource consumption rather than heavy collaboration features or enterprise complexity.\n\n---\n\n## Project Structure\n\n```\nhiai-docs/\n├── backend/              # Elysia REST API\n│   ├── src/\n│   │   ├── api/          # Routes + middleware\n│   │   ├── lib/          # Shared utilities\n│   │   ├── embedding/    # Embedding pipeline\n│   │   └── index.ts      # Entry point\n│   ├── package.json\n│   └── tsconfig.json\n├── frontend/             # SvelteKit web UI\n│   ├── src/\n│   │   ├── routes/       # Pages\n│   │   ├── lib/          # Components + utils\n│   │   └── app.css       # Tailwind + theme\n│   ├── package.json\n│   └── svelte.config.js\n├── packages/db/          # Drizzle schema + migrations\n│   ├── src/\n│   │   ├── schema.ts     # Table definitions\n│   │   ├── migrations/   # SQL migrations\n│   │   └── index.ts      # DB client\n│   └── package.json\n├── docker-compose.yml    # Production Docker setup\n├── .env.example          # Environment template\n├── AGENTS.md             # Agent instructions\n├── README.md             # This file\n├── LICENSE               # MIT\n└── todo.md               # Development roadmap\n```\n\n---\n\n## Configuration\n\nAll configuration via environment variables. Copy `.env.example` to `.env` and configure:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DB_USER` | aiuser | PostgreSQL username |\n| `DB_PASSWORD` | changeme | PostgreSQL password |\n| `BETTER_AUTH_SECRET` | — | Auth secret (generate random) |\n| `BETTER_AUTH_URL` | http://localhost:50700 | Auth base URL |\n| `MINIO_ACCESS_KEY` | minioadmin | MinIO access key |\n| `MINIO_SECRET_KEY` | minioadmin | MinIO secret key |\n| `EMBEDDING_BASE_URL` | — | Base URL for OpenAI-compatible embedding API (optional) |\n| `EMBEDDING_API_KEY` | — | API key for embedding service (leave empty for local inference) |\n| `EMBEDDING_MODEL` | — | Embedding model name |\n| `CORS_ORIGINS` | http://localhost:50701 | Comma-separated allowed origins (required for local dev) |\n\nSee `.env.example` for full list of all configuration variables.\n\n---\n\n## API Documentation\n\nREST API available at `http://localhost:50700/api/`.\n\nKey endpoints:\n- `POST /api/documents` — Create document\n- `GET /api/documents/:id` — Get document with tags\n- `GET /api/search?q=query` — Hybrid full-text + semantic search\n- `POST /api/share` — Create share link\n- `GET /api/share/:token` — Access shared content (public)\n- `POST /api/documents/:id/attachments` — Upload image\n- `WS /ws/collab/:documentId` — Real-time collaborative editing\n\nFull API documentation available in [docs/API.md](docs/API.md).\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing`)\n3. Commit changes (`git commit -m 'feat: add amazing feature'`)\n4. Push to branch (`git push origin feature/amazing`)\n5. Open a Pull Request\n\n### Development Rules\n\n- **Bun only** — no npm/yarn\n- **ESM only** — no CommonJS\n- **TypeScript strict** — no `any`\n- **English only** — code, comments, docs, commits\n- **No Playwright** — use agent-browser for E2E\n\n---\n\n## License\n\n[MIT](LICENSE)\n\n---\n\n## Related Projects\n\nPart of the [HiAi](https://hiai.gg) open-source ecosystem:\n\n| Project | Description |\n|---------|-------------|\n| [hiai-opencode](https://github.com/hiai-gg/hiai-opencode) | AI coding agent |\n| [hiai-observe](https://github.com/hiai-gg/hiai-observe) | Observability platform |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiai-gg%2Fhiai-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhiai-gg%2Fhiai-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhiai-gg%2Fhiai-docs/lists"}