Skip to content
Uvilo OS
draft Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

TinaCMS Research

Context

Uvilo OS currently supports two editing surfaces: direct file editing via Git (command line or GitHub) and AI-assisted editing via LibreChat MCP tools on Railway. A third surface — a visual, browser-based content editor — would enable non-technical team members to edit documentation without Git knowledge. TinaCMS is the leading candidate.

What is TinaCMS?

TinaCMS is an open-source, Git-backed headless CMS. It provides a visual editing interface that commits changes directly to a Git repository. It supports Markdown and MDX content with a customizable schema. TinaCMS can be self-hosted (free) or used as a managed cloud service.

Key properties:

  • Git-native: all edits become Git commits
  • Real-time visual editing with live preview
  • Schema-driven: content types defined in code
  • Self-hostable via Docker (free, open source)
  • Managed cloud available (Tina Cloud)

Why TinaCMS for Uvilo OS?

  1. Git-backed: edits are commits — no separate database, single source of truth preserved
  2. Visual editing: team members can edit Markdown docs in a WYSIWYG interface
  3. Schema validation: frontmatter fields (visibility, status, owner, etc.) are enforced
  4. Self-hostable: can run alongside LibreChat on Railway
  5. Compatible with Astro/Starlight content structure

Architecture

Self-hosted Setup

TinaCMS self-hosted requires:

  1. TinaCMS backend — a Node.js server that handles Git operations, authentication, and the GraphQL API
  2. TinaCMS frontend — the editing UI, which can be embedded in the Starlight site or served separately
  3. Authentication — Auth.js (NextAuth), Cloudflare Access, or a custom auth provider
  4. Git access — the backend needs read/write access to the uvilo-os repository

Deployment on Railway

The TinaCMS self-hosted backend would run as a Railway service alongside LibreChat, sharing the same persistent volume and Git clone. This means:

  • TinaCMS and LibreChat both edit the same Git working copy
  • Changes from either surface are visible to the other after a git pull
  • Both surfaces commit under appropriate user identities

Content Schema

TinaCMS schema must match the Uvilo OS frontmatter standard:

title: string (required)
description: string (optional)
visibility: enum [internal, public] (default: internal)
status: enum [draft, review, approved, published, archived] (default: draft)
owner: string (email)
approver: string (email)
lastUpdated: date (optional)
version: number (optional)

The schema is defined in tina/config.ts and maps to the Astro content collection schema in content.config.ts.

Multi-user Considerations

  • Each user’s edits should be attributed to their Git identity (name + email)
  • TinaCMS self-hosted can be configured to use the authenticated user’s identity for commits
  • This aligns with the LibreChat multi-user path expansion work (Task 4)