Skip to content

README.md

Latest commit

 

History

History
237 lines (168 loc) · 8.99 KB

README.md

File metadata and controls

237 lines (168 loc) · 8.99 KB
Pageel CMS

Pageel CMS

A lightweight, self-hosted and Git-based CMS native for Astro

Manage your content where your code lives. No database required.

License Version Status GitHub Astro Node.js


🇺🇸 English | 🇻🇳 Tiếng Việt


A lightweight, self-hosted Content Management System that uses your GitHub repository as the content backend. No external database — your Markdown/MDX files and images live right in your repo. Built with Astro 6 and React 19, featuring server-side authentication and a Notion-inspired editing experience.

📸 Screenshots

Pageel Dashboard Preview

✨ Key Features

Feature Description
📚 Multi-Collection Manage multiple content types (Blog, Docs, Projects) in one workspace
🏷️ Typed Templates Define schema with String, Date, Boolean, Number, Array, Object
🔍 Smart Filtering Auto-generated filter UI based on your template types
🧩 Plugin System Slot-based WYSIWYG editor plugins (MDXEditor included) with CSS isolation
🔐 Server-Side Auth Env Auth with bcrypt — your Git token never leaves the server
🔀 Multi-Tenant One deployment, multiple repos — each user provides their own token at login
🌐 i18n Ready English and Vietnamese support
⚡ Optimistic Locking SHA-check prevents overwriting concurrent changes
🚀 Self-Hosted Deploy on any VPS, Docker, or serverless platform

🏗️ Architecture (v2.0)

┌─────────────────────────────────────────────┐
│              Browser (React SPA)            │
│  Dashboard, PostList, Images, Templates     │
│         ProxyGitAdapter → /api/proxy/*      │
└─────────────┬───────────────────────────────┘
              │ Cookie session (HMAC-SHA256)
┌─────────────▼───────────────────────────────┐
│           Astro SSR Server (Node.js)        │
│  middleware.ts → session guard              │
│  /api/auth/login → bcrypt verify            │
│  /api/proxy/git → GitHub API (server-side)  │
│  /api/proxy/upload → file upload via API    │
│  /api/proxy/blob → binary file serving      │
└─────────────────────────────────────────────┘

Tech Stack

Astro React TypeScript Tailwind CSS

Security Model

  • No client-side tokens: Git PAT stored server-side only (env or encrypted in session cookie)
  • Bcrypt password hashing: 12-round bcrypt with constant-time comparison
  • HMAC-SHA256 sessions: Signed cookies with HttpOnly + SameSite=Strict + Secure
  • Token validation at login: Dynamic tokens are verified against GitHub API before session is created
  • Rate limiting: 5 attempts per minute per IP
  • Upload hardening: Path validation blocklist + file type/size limits on upload proxy

🧩 Plugin System (v2.1 — Beta)

Pageel CMS features a slot-based plugin architecture for extending the editor experience.

Available Plugins

Package Description Status
@pageel/plugin-types TypeScript interfaces for plugin development ✅ Ready
@pageel/plugin-mdx MDXEditor WYSIWYG editor with toolbar, image upload, debounce ✅ Ready
@pageel/cms Astro integration — auto-detect collections, inject /cms route ✅ Ready

Enable WYSIWYG Editor

Add to your .pageelrc.json:

{
  "version": 2,
  "plugins": {
    "editor": "@pageel/plugin-mdx"
  }
}

3-Tab Editing

Tab Description
✏️ Edit WYSIWYG editor (MDXEditor plugin) or fallback textarea
</> Markdown Raw markdown editor — always available
👁 Preview Rendered HTML preview

🚀 Getting Started

Prerequisites

  • Node.js >= 22.12.0
  • A GitHub repository with markdown content
  • A GitHub personal access token (fine-grained recommended)

1. Clone & Install

git clone https://github.com/pageel/pageel-cms.git
cd pageel-cms
npm install

2. Configure Environment

cp .env.example .env

Edit .env with your credentials:

CMS_USER=admin
CMS_PASS_HASH="$2a$12$..."   # See docs/deployment.md for hash generation
CMS_SECRET=your-random-secret-min-16-chars

# Optional — if omitted, users provide these at login (Multi-Tenant mode)
GITHUB_TOKEN=ghp_your_token
CMS_REPO=username/repo

💡 Two modes: Set GITHUB_TOKEN + CMS_REPO for a dedicated single-repo setup (Server Mode). Leave them empty to let each user provide their own token and repo at login (Connect Mode / Multi-Tenant).

3. Run Development Server

npm run dev

Open http://localhost:4321 — you'll be redirected to /login.

4. Generate Password Hash

# After npm install (step 1)
npx pageel-cms hash your-password

# Or without project installed:
node -e "require('bcryptjs').hash('your-password', 12).then(h => console.log(h))"

Copy the output hash to CMS_PASS_HASH in your .env file (wrap in double quotes).

5. Production Build

npm run build
node dist/server/entry.mjs

See docs/deployment.md for VPS, Docker, and Vercel deployment guides.

📚 Documentation

Document Description
Setup & Auth Modes Installation guide with detailed 3-mode configuration (Server, Connect, Open)
Deployment VPS, Docker, Vercel deploy guides, env vars reference
Security Assessment Auth, session, proxy security review
Plugin Development TypeScript interfaces for building custom plugins

🌐 Ecosystem

Product Type Purpose
Pageel CMS OSS (MIT) Git-native CMS for content & media
@pageel/plugin-mdx OSS (MIT) WYSIWYG editor plugin (MDXEditor)
@pageel/cms OSS (MIT) Astro integration bridge
Pageel Workhub Commercial Team workspace: workflow, review, permissions

Pageel CMS focuses on content. For team collaboration features, see Pageel Workhub.

🤝 Contributing

Contributions are welcome!

  1. Fork the repository
  2. Create feature branch (git checkout -b feature/amazing-feature)
  3. Commit changes (git commit -m 'Add amazing feature')
  4. Push to branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License. See the LICENSES.md file for details.

Made with ❄️ by Pageel