{"id":51135370,"url":"https://github.com/zcag/tela","last_synced_at":"2026-06-25T17:30:28.193Z","repository":{"id":362776366,"uuid":"1242321286","full_name":"zcag/tela","owner":"zcag","description":"Open-source, self-hostable markdown team wiki with a built-in MCP server — so AI agents read, write, and search your docs as first-class teammates. Live multiplayer, semantic + full-text search. Go + PostgreSQL + React/Milkdown.","archived":false,"fork":false,"pushed_at":"2026-06-21T14:23:10.000Z","size":7172,"stargazers_count":2,"open_issues_count":4,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-21T14:34:19.444Z","etag":null,"topics":["ai-agents","confluence-alternative","documentation","golang","knowledge-base","markdown","mcp","model-context-protocol","notion-alternative","postgresql","react","self-hosted","team-collaboration","wiki","yjs"],"latest_commit_sha":null,"homepage":"https://tela.cagdas.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zcag.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T10:17:41.000Z","updated_at":"2026-06-21T14:23:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/zcag/tela","commit_stats":null,"previous_names":["zcag/tela"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/zcag/tela","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcag%2Ftela","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcag%2Ftela/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcag%2Ftela/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcag%2Ftela/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zcag","download_url":"https://codeload.github.com/zcag/tela/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zcag%2Ftela/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34786224,"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-25T02:00:05.521Z","response_time":101,"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-agents","confluence-alternative","documentation","golang","knowledge-base","markdown","mcp","model-context-protocol","notion-alternative","postgresql","react","self-hosted","team-collaboration","wiki","yjs"],"created_at":"2026-06-25T17:30:27.509Z","updated_at":"2026-06-25T17:30:28.183Z","avatar_url":"https://github.com/zcag.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/submission-assets/logo-lockup-dark.svg\"\u003e\n  \u003cimg alt=\"tela\" src=\"docs/submission-assets/logo-lockup-light.svg\" width=\"184\"\u003e\n\u003c/picture\u003e\n\n# tela\n\nA self-hostable, markdown-native team wiki — spaces, nested pages, a Milkdown editor, ranked full-text + semantic search, live collaboration, comments, page history, public sharing, and a first-class MCP server so AI agents are first-class citizens alongside humans.\n\nPublic instance: **https://tela.cagdas.io**\n\n## Stack\n\n| Part       | Tech                                                                                         | Location    |\n|------------|---------------------------------------------------------------------------------------------|-------------|\n| Backend    | Go + PostgreSQL (`pgx/v5` stdlib), `database/sql` (no ORM), embedded migrations              | `backend/`  |\n| Frontend   | React 19 + TypeScript + Vite + Tailwind v4 + Radix + Milkdown + TanStack Query/Router + Orama | `frontend/` |\n| Collab     | Yjs + y-prosemirror over a custom WebSocket transport (not y-websocket)                      | `frontend/` |\n| MCP server | TypeScript (`@modelcontextprotocol/sdk`), published to npm as `tela-mcp`                     | `mcp/`      |\n| Deploy     | Docker Compose — backend, frontend (nginx), Postgres, Caddy proxy; data on a Postgres volume | `deploy/`   |\n\n`pages.body` is canonical markdown forever; there is no block table. The editor is Milkdown; Yjs is an overlay that rebases onto the markdown on save.\n\n## Quickstart (local dev)\n\n```bash\nmake dev        # backend (go run ./cmd/tela, :8080) + frontend (vite, :5173) in parallel\n```\n\nThe Vite dev server proxies `/api` → backend `:8080`. `make dev` boots a local Postgres (`tela-dev-pg` on :55433) and points `TELA_DATABASE_URL` at it; the schema is migrated automatically on backend start (embedded migrations run by `db.Migrate()` — no separate migrate step). Open http://localhost:5173.\n\nRun parts individually:\n\n```bash\nmake be-dev     # backend only (go run ./cmd/tela)\nmake fe-dev     # frontend only (vite)\nmake storybook  # Storybook — the component dev surface (:6006)\n```\n\n## Production (Docker Compose)\n\n```bash\nmake setup                           # write deploy/.env from the example with generated secrets\n$EDITOR deploy/.env                  # set admin creds, public base URL, SMTP\nmake up                              # build + start the stack (Docker only — no host Node)\nmake logs                            # tail logs\nmake down                            # stop\n```\n\nThe stack publishes a single host port **8780** (Caddy). `make setup` fills the\nload-bearing secrets (`TELA_SHARE_SECRET`, `TELA_API_KEY_SECRET`,\n`TELA_PG_PASSWORD`); set `TELA_PUBLIC_BASE_URL` and the `TELA_ADMIN_*` /\n`TELA_SMTP_*` values yourself. If you leave the HMAC secrets unset entirely,\ntela now generates and **persists** them on first boot (stable across restarts).\n\n**Full setup, TLS, backups, and upgrades: see [`docs/self-hosting.md`](docs/self-hosting.md)** and the operations runbook [`docs/operations.md`](docs/operations.md). `deploy/.env.example` documents every variable.\n\n## Make targets\n\n```\nmake setup      # first run: write deploy/.env from the example with generated secrets\nmake dev        # backend + frontend in dev mode (parallel, no compose)\nmake be-dev     # backend only           make fe-dev     # frontend only\nmake storybook  # Storybook\nmake up         # build + start the compose stack on :8780 (stamps version/commit)\nmake down       # stop          make logs   # tail logs       make build  # rebuild images\nmake backup     # dump Postgres to ./backups   make restore FILE=...  # restore a dump\nmake clean FORCE=1            # stop AND delete volumes (destroys data)\nmake test-mcp-integration     # boot stack + run MCP↔backend E2E + tear down\nmake help\n```\n\n\u003e Note: there is no `make lint` or `make migrate` — migrations run automatically on backend start. `make test` runs the backend suite (below).\n\n## Tests\n\n```bash\nmake test                       # backend (boots a throwaway Postgres; per-test isolated DBs)\ncd mcp \u0026\u0026 npm test              # MCP unit (mocked fetch) + npm run test:smoke / test:integration\n```\n\nThe frontend has **no** unit-test harness today (no jsdom / vitest config). CI (`.github/workflows/ci.yml`) runs the MCP↔backend integration suite on changes to `backend/`, `mcp/`, `deploy/`, or the Makefile.\n\n## Documentation\n\n- [`docs/architecture.md`](docs/architecture.md) — system shape, repo layout, data model, and per-subsystem load-bearing details\n- [`docs/decisions.md`](docs/decisions.md) — why PostgreSQL, custom collab transport, MCP-as-thin-client, etc.\n- [`docs/api.md`](docs/api.md) — REST API surface\n- [`CLAUDE.md`](CLAUDE.md) — conventions, hard rules, and the gotchas — **read before contributing**\n- [`mcp/README.md`](mcp/README.md) — the MCP server (install, tool catalog, troubleshooting)\n\n## History\n\ntela was originally built by an autonomous agent system (\"forge\") and is now under conventional development. The old forge workspace (plan, run logs, task/idea history, research output under `docs/output/`) is archived out-of-tree — reference only, not part of this repo. This repo's code, `docs/`, and git history are the source of truth.\n\n## License\n\nCopyright © tela contributors. Licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0). You may self-host, modify, and redistribute tela under its terms — in particular, if you run a modified version as a network service you must offer your users the corresponding source. For a commercial license without AGPL obligations (e.g. to embed or offer tela as a closed service), contact the maintainer.\n\n**\"tela\", the tela name, and the tela logo are trademarks** and are **not** licensed under the AGPL — see [TRADEMARK.md](TRADEMARK.md). You may run and fork the code, but you may not use the tela branding for a redistributed or hosted version without permission.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzcag%2Ftela","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzcag%2Ftela","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzcag%2Ftela/lists"}