# Project pack: Docmost @ b007d8c

Facts about **Docmost** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v2.md). This pack is pinned to one version and never changes after publication.

> Docmost is an open-source collaborative wiki, a Notion or Confluence alternative you host yourself. People edit pages together in real time, organise them into spaces, comment, share pages publicly, and embed diagrams. It suits a family handbook, a club or a small business.

## Version and source
- Repository: https://github.com/docmost/docmost
- Pinned commit: `b007d8cb214e95fddda861eb15d24e51eb0b90b3`. Use exactly this version.
- Fresh checkout: use the setup below in an empty folder. If you already have this exact source checked out, keep your branch and use the development command instead; do not clone again or reset local changes.
- Or download a zip: https://github.com/docmost/docmost/archive/b007d8cb214e95fddda861eb15d24e51eb0b90b3.zip
- Official docs: https://docmost.com/docs
- Licence: **AGPL-3.0-only**. Free to use and change. If other people use your changed version, including over a network (for example a website you host for them), you must offer them your source code under the same licence. Using it privately for yourself or your household has no extra obligations. A packages/ee folder is under a separate commercial licence and should not be reused.

## Running the pinned source
- Fresh pinned-source setup (skip clone and checkout in an existing worktree):

  ```sh
  git clone https://github.com/docmost/docmost bespoke-docmost
  cd bespoke-docmost
  git checkout --detach b007d8cb214e95fddda861eb15d24e51eb0b90b3
  # Prepare development requirements and local configuration first.
  corepack enable
  pnpm install
  cp .env.example .env
  pnpm dev
  ```

The commands below are a starting point from the reviewed source. Prepare the listed tools, local configuration and companion services before starting the app. These instructions have not yet been validated in participant sessions.

### Separate trial of the current release
This tries an upstream release, which may differ from the pinned source above. It does not run your source changes. Use only sample data and a separate data directory or volume. Check the upstream documentation before running it.

  ```sh
  curl -O https://raw.githubusercontent.com/docmost/docmost/main/docker-compose.yml
  # edit APP_SECRET and the database password in the file first
  docker compose up -d
  # then open http://localhost:3000
  ```

- Needs: Docker, or Node 22 with pnpm plus Postgres and Redis for development
- Develop: `pnpm dev`
- Build: `pnpm build`
- Stack: typescript (NestJS, React, Mantine, Tiptap, Nx, pnpm). Difficulty for a non-developer with an AI: **advanced**. A TypeScript monorepo with a NestJS server, a React client and a collaboration server, backed by Postgres and Redis. Branding and workspace settings need no code; new features touch client and server.

## Customisation points (settings → extend → code)
- **workspace-settings** [settings]: Who can see and edit which spaces, and public sharing. → `Workspace → Settings (spaces, members, groups, sharing)`
- **email-and-storage** [settings]: Where invitations are sent from and where files are stored. → `Environment variables in .env (mail driver, storage driver)`
- **editor-extensions** [code]: New blocks and editor features. → `packages/editor-ext/src`
- **server-modules** [code]: New API features such as labels, comments or sharing rules. → `apps/server/src/core`
- **client-screens** [code]: New pages, menus and styling. → `apps/client/src`

## Must keep working
- Real-time collaboration (the collaboration server and Redis).
- Permissions, meaning space roles, groups and page sharing rules.
- Database migrations in apps/server/src/database/migrations (add new ones; never edit old).

## Staying updatable
Use settings and environment variables first. Keep code changes in new modules or components, and stay away from packages/ee.

## Data, costs and safety
- Personal data: **yes**. Stored in: Postgres database plus an attachments folder (a Docker volume). Back up both the database and the attachments volume.
- Service: Email (SMTP or Postmark) (optional, usually free to a few dollars): Invitations and password resets.
- Service: File storage (local disk or S3) (optional, free locally): Page attachments.
- Setting `APP_URL`: The address people use to reach your Docmost.
- Setting `APP_SECRET` (**secret**: the person enters it themselves, never in chat): A long random secret used to sign logins. Never paste it into an AI chat.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Postgres connection string. Contains a password.
- Setting `REDIS_URL`: Redis address used for queues and live editing.
- Set a long random APP_SECRET and never commit your .env file.
- Check which spaces and pages are shared publicly before inviting others.
- Run behind HTTPS if it is reachable from the internet.

---

# Customising Docmost

Docmost is a pnpm and Nx monorepo: a NestJS server, a React client, and a shared editor package. Run it in Docker first to see how it behaves.

## How the code is laid out

| You want to change… | Look in |
|---|---|
| Screens, menus and styling | apps/client/src/ |
| Page editor blocks | packages/editor-ext/src/ |
| API features (pages, spaces, comments, sharing) | apps/server/src/core/<feature>/ |
| Integrations (mail, storage, queue, export, import) | apps/server/src/integrations/ |
| Database tables and migrations | apps/server/src/database/ |
| Real-time collaboration | the collab server in apps/server/src/collaboration/ |
| Commercial features | packages/ee/ (separate licence, don't reuse) |

## Use the gentlest change first

1. **Settings (no code):** spaces, groups, permissions, public sharing, and the mail and storage settings in `.env`.
2. **Extend:** use the API and import/export to bring in your existing notes.
3. **Code:** editor blocks, server features and screens. Keep new code in new files.

## Recipes

- **New field on pages:** add a Kysely migration, update the page entity and repo, expose it in the controller, then show it in the client.
- **New editor block:** build a Tiptap extension in `packages/editor-ext`, then register it in the client editor.

## Running and checking your changes

- `pnpm dev` starts server and client together, with Postgres and Redis running.
- `pnpm build` must pass before you finish.
- Open the same page in two browsers to test live editing.

## Pitfalls

- Don't edit old migrations. Add new ones.
- Don't commit `.env` or database dumps.
- Leave `packages/ee` alone. It is under a different licence.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/docmost/b007d8c/r2/bespoke.yaml) · Hosting options: [hosting.md](https://handoff.bespokeai.software/p/docmost/b007d8c/r2/hosting.md) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/docmost/b007d8c/r2/SKILL.md)