UP Docs
README.md
# UP Docs
[](https://deploy.workers.cloudflare.com/?url=https://github.com/riccardovandra/up-docs)
Collaborative markdown docs for people and agents, on your own Cloudflare account. One Cloudflare Worker serves the web app, a JSON API under `/api`, and an MCP endpoint under `/mcp` for agents. Each doc has a Durable Object that applies every write in order and pushes it to open editors over WebSocket. Data lives in D1, doc images in R2, or in D1 if you remove the R2 binding. Uploaded videos always live in R2.
UP Docs can run inside [T3 Code](https://github.com/pingdotgg/t3code)'s Docs panel. `FRAME_ANCESTORS` in `wrangler.jsonc` lists the origins allowed to frame the app. `src/shared/embed.ts` holds the postMessage protocol.
## Deploy
### Before you click
- **R2 may need a payment method.** Images go to an R2 bucket by default, and Cloudflare may require a payment method on the account before it creates one. We have not confirmed this on an account with no card. If the deploy fails on the R2 bucket, either add a payment method, or remove the `r2_buckets` line from `wrangler.jsonc` and deploy again. Images are then stored in D1, and uploading videos is turned off.
- **Choose an admin password** of 12 or more characters. Shorter or empty turns password sign-in off, and with no email set up you then cannot sign in at all.
### What the button does
The button itself has not been pressed in testing. These steps were run through the same Workers Builds service with the same commands, and the setup page is described from Cloudflare's documentation.
1. Cloudflare copies this repo to your GitHub or GitLab account, and asks for the project and Worker names, the resource names, and `ADMIN_PASSWORD`.
2. It prefills the build command and deploy command from `package.json`. Keep them, for example `bun run build` and `bun run deploy`. The deploy command needs a POSIX shell, which the Workers Builds image has.
3. Workers Builds installs with `bun install --frozen-lockfile`, builds, creates the D1 database and R2 bucket, applies the migrations, and deploys.
4. On the first deploy the log shows `Couldn't find a D1 DB`, marked as an error. This is expected: the database does not exist until the deploy creates it. The build continues and ends with `Success! Build completed`.
Your app is live at `https://<worker>.<your-subdomain>.workers.dev`. Sign in there with the password.
### After deploying
- **Add agents.** In the app, open Settings and create an API token. In T3 Code, open Settings -> MCP servers and add `https://<your-worker-url>/mcp` with that token. Agents act as the person who created the token.
- **Add email, for invites and other people's sign-in.** Without it, sharing still records the person and tells you no email was sent, and they cannot sign in until email works. To add it, verify a domain in [Resend](https://resend.com/domains), then in the Worker's settings add the secret `RESEND_API_KEY` and the variable `EMAIL_FROM`, such as `UP Docs <docs@example.com>`. Both are needed: with only the key, the app reports email as not configured and sends nothing. Deploys keep values set in the dashboard.
- **Sign in as admin by email (optional).** Set the variable `OWNER_EMAILS` to a comma-separated list of addresses. Anyone else can sign in once a doc has been shared with their address.
- **Use a custom domain (optional).** Add it to the Worker, then set the variable `PUBLIC_ORIGIN` to its origin, such as `https://docs.example.com`. Unset, the app uses the origin of each request.
- **Embedding.** `FRAME_ANCESTORS` in `wrangler.jsonc` controls who may frame the app. The default allows T3 Code and its local origins.
### Deploy with Wrangler
Requires [Bun](https://bun.sh) and a POSIX shell, so on Windows use WSL.
```sh
git clone https://github.com/riccardovandra/up-docs
cd up-docs
bun install --frozen-lockfile
bunx wrangler login
bun run deploy
bunx wrangler secret put ADMIN_PASSWORD
```
`bun run deploy` builds, applies migrations and deploys, creating the D1 database and R2 bucket when they are missing. The same `Couldn't find a D1 DB` message appears on the first run.
### Check a deployment
```sh
ADMIN_PASSWORD=<password> bun scripts/smoke.ts https://<your-worker-url>
```
It signs in, creates and edits a doc, uploads an image and a video, uses `/mcp` with a new API token, checks sharing, then removes what it created. The sharing step fails when email is configured, because it expects no email to be sent.
### Videos
A doc plays YouTube links, Loom links and uploaded MP4, WebM and MOV files. In the editor, use "Video link" or "Upload video" in the "+" menu, or drop a file on the page. Agents write a `t3-video` block, whose first line is the source and whose optional second line is the title:
````
```t3-video
https://www.youtube.com/watch?v=dQw4w9WgXcQ
Release walkthrough
```
````
- YouTube and Loom load only when a reader clicks play. Nothing contacts them before that.
- Uploads need R2. Without the bucket the API answers `video_storage_unavailable` and the editor says so. Links still work.
- Files are capped at 1 GiB and go through the Worker in 50 MiB parts. They use the `IMAGES` bucket under a `videos/` prefix, so there is nothing extra to configure.
- Removing a video block does not delete the file. Files go when the doc is deleted. R2 storage costs about $0.015 per GB-month, and egress is free.
- Inside T3 Code, fullscreen and player autoplay need T3 Code to pass `fullscreen; autoplay` to the docs iframe. Until that ships, videos play there with these two limits.
### Diagrams
The library has a Docs and Diagrams switch. A diagram is a [Draw.io](https://www.drawio.com) drawing kept next to your docs: "New diagram" opens the Draw.io editor over the page, and Save & Exit stores the drawing with a picture of it. Each diagram has its own page to reopen, rename or delete it.
- The editor is the hosted `https://embed.diagrams.net/`, loaded in a frame. The drawing is handed to that frame in the browser and saved back to this app; UP Docs does not send it anywhere else.
- A diagram is stored once, as Draw.io XML of up to 1 MB, with an SVG and a PNG picture in R2, or in D1 without a bucket.
- Its creator and the admin manage it. The block that links a diagram into a doc is `t3-drawio`, whose first line is the diagram's id and whose optional second line is a caption; the doc editor does not draw that block yet. Anyone who can read a doc that links a diagram can see its picture, and nothing else.
- Two people saving the same diagram do not overwrite each other silently: the second save is told, and chooses to overwrite or to reload.
- A diagram whose picture is missing or out of date is drawn again by the next browser that shows it to someone who manages it.
### Embedded posts
A doc can show a LinkedIn post, an X post or an X article in place of its link. LinkedIn and X posts show the provider's own embed, as their "Embed this post" option gives it. In the editor, paste the link on an empty line (undo turns it back into a plain link), or use "Embed post" in the "+" menu. Agents write a `t3-embed` block, whose first line is an https link and whose optional second line is a caption:
````
```t3-embed
https://www.linkedin.com/posts/name_slug-activity-7209442266791186432-uyzh
Hook: a number in the first line
```
````
- `t3-embed compact` shows only the author and the first two lines, with no image, until a reader clicks "Show post". Editors switch a block with "Compact" and "Full size". Use it for docs with many posts.
- The first time a doc with the block is opened, the Worker fetches the post once and saves a copy for that doc: author, full text, date, like and comment counts, and the post's image as a doc image. "Saved copy" shows it, and it is what remains if the post is deleted. Compact blocks and X articles render from it. Editors can retake it with "Refresh copy".
- The provider's embed runs in a sandboxed frame that cannot navigate the doc, submit forms or open dialogs, and loads when it scrolls into view, so LinkedIn and X see readers of full-size embeds. A compact block contacts neither until it is expanded. No provider HTML reaches the page itself: the copy is plain text, and its image is served from the doc's own images.
- Any other https link shows as a link card. So do posts that are private, deleted, or that the provider refuses to serve. X articles have no public embed, so they show a copy only when X serves their preview tags, and a link card otherwise.
- X posts are read from the feed X's own embed widget uses. It is not a documented API and may change; if it does, X posts fall back to link cards.
- Copies live in D1 and their images in R2, or in D1 without a bucket. A doc holds at most 500 copies. They go when the doc is deleted.
### Cloudflare plan limits
UP Docs has not been tested on the Workers Free plan, so we do not claim it works there. Free allows 10 ms of CPU per request, and we measured, on a single account whose plan limits we did not verify, with a 10 MiB image:
| Image store | Upload CPU | Fetch CPU |
| ----------- | ------------ | ----------------- |
| R2 | 7 to 16 ms | 1 to 2 ms |
| D1 | 49 to 133 ms | not measured here |
Both uploads can exceed the 10 ms limit, the D1 path by far, so expect large image uploads to be at risk on Free. Smaller images use less. R2 and D1 have their own usage limits; check Cloudflare's current pricing.
## Local development
Requires [Bun](https://bun.sh).
```sh
bun install --frozen-lockfile
bun run dev # builds the app, applies local D1 migrations, starts wrangler dev on :8787
```
Put `ADMIN_PASSWORD=<12 or more characters>` in `.dev.vars` (gitignored) and sign in with it. For email sign-in, add `OWNER_EMAILS=you@example.com` there; on localhost, with no `RESEND_API_KEY`, the code is printed to the `wrangler dev` console, and on any other host it is never logged. Override any other var the same way, such as `PUBLIC_ORIGIN=http://localhost:<port>` on another port. Run `bun run build` after client changes.
## Tests
```sh
bun run test
bun run typecheck
bun run build
```
## License
MIT. See [LICENSE](LICENSE).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues