mini-cms

A minimal CMS that connects directly to your GitHub repositories. Edit MDX and Markdown files with ease.

🚀 Features

🔗 GitHub Integration

• Direct Repository Connection: Connect seamlessly to your GitHub repositories
• Version Control Built-in: All changes are tracked through GitHub's version control
• GitHub App Installation: Easy setup through GitHub App integration
• Multi-Organization Support: Manage multiple organizations and repositories

✍️ Rich Text Editor

• MDX & Markdown Support: Edit MDX and Markdown files with a powerful WYSIWYG editor
• Live Preview: See your changes in real-time as you edit
• Syntax Highlighting: Code blocks with proper syntax highlighting
• Draft Management: Auto-save drafts to prevent data loss

📁 Project Management

• Organization System: Create and manage multiple organizations
• Project Workspace: Organize content by projects
• File Explorer: Navigate through your repository files easily
• Commit History: Track all changes with detailed commit messages
• Permission Management: Control access with role-based permissions

🔐 Authentication & Security

• Multiple OAuth Providers: GitHub and Google OAuth integration
• JWT-Based Authentication: Secure token-based authentication
• Token Rotation: Automatic refresh token rotation for enhanced security
• Redis Blacklisting: Token revocation with Redis for logout and security
• Automatic Token Refresh: Seamless user experience with middleware-based token refresh

👥 Team Collaboration

• Member Invitations: Invite team members via email
• Role Management: Assign different roles to team members
• Activity Tracking: Monitor project activity and changes
• Shared Workspaces: Collaborate on content with your team

🛠️ Tech Stack

• Frontend: Astro + Alpine.js + React
• Backend API: Hono (Node.js)
• Database: Astro DB (LibSQL/Turso)
• Cache/Sessions: Upstash Redis
• Authentication: JWT (jsonwebtoken) + OAuth 2.0
• GitHub Integration: @octokit/rest
• Editor: @mdxeditor/editor
• Styling: Tailwind CSS
• Email: Nodemailer
• Validation: Zod

📦 Installation

Prerequisites

• Node.js 18+ and pnpm
• GitHub account
• Upstash Redis account
• Gmail account (for email notifications)

Environment Variables

Create a .env file in the root directory:

# Database
ASTRO_DB_REMOTE_URL=your_turso_database_url
ASTRO_DB_APP_TOKEN=your_turso_app_token

# GitHub OAuth
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_APP_ID=your_github_app_id
GITHUB_APP_PRIVATE_KEY=your_github_app_private_key

# Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

# JWT Secrets
JWT_SECRET_KEY=your_jwt_secret
JWT_REFRESH_SECRET=your_refresh_secret

# Redis (Upstash)
UPSTASH_URL=your_upstash_redis_url
UPSTASH_TOKEN=your_upstash_token

# Email (Gmail)
EMAIL_USER=your_gmail_address
EMAIL_PASS=your_gmail_app_password

# App Configuration
PUBLIC_BASE_URL=http://localhost:4321

Setup

1. Clone the repository

   git clone https://github.com/yourusername/mini-cms.git
   cd mini-cms

2. Install dependencies

   pnpm install

3. Set up environment variables

   cp .env-sample .env
   # Edit .env with your credentials

4. Set up database

   pnpm astro db push --remote

5. Run development server

   pnpm dev

   The app will be available at http://localhost:4321

🧞 Commands

All commands are run from the root of the project:

Command	Action
pnpm install	Install dependencies
pnpm dev	Start local dev server at localhost:4321
pnpm build	Build your production site to ./dist/
pnpm preview	Preview your build locally before deploying
pnpm astro db ...	Run Astro DB CLI commands
pnpm astro check	Run TypeScript type checking

📚 Project Structure

/
├── db/                         # Database schema definitions
│   ├── user.ts                 # User table schema
│   ├── orgs.ts                 # Organizations table
│   └── projects.ts             # Projects table
├── src/
│   ├── actions/                # Astro Actions (server functions)
│   ├── components/
│   │   ├── dashboard/          # Dashboard UI components
│   │   ├── landing/            # Landing page components
│   │   └── ui/                 # Reusable UI components
│   ├── layouts/                # Page layouts
│   ├── lib/
│   │   └── server/             # Server-side logic
│   │       ├── auth/           # Authentication service
│   │       ├── organizations/  # Organization management
│   │       ├── projects/       # Project management
│   │       └── repo/           # GitHub repository integration
│   ├── middleware.ts           # Auth middleware & token refresh
│   ├── pages/                  # Page routes
│   └── store/                  # Client-side state management
└── public/                     # Static assets

🔑 Key Features Implementation

Authentication Flow

1. Login: User authenticates via GitHub or Google OAuth
2. Token Generation: JWT access token (15m) and refresh token (7d) are issued
3. Middleware: Checks and auto-refreshes expired tokens
4. Logout: Tokens are blacklisted in Redis

GitHub Integration

1. GitHub App: Install the GitHub App on your repositories
2. Repository Access: Grant access to specific repositories
3. File Management: Edit files directly through the CMS
4. Commit Changes: All edits create commits in your repository

Project Workflow

1. Create Organization: Set up an organization for your team
2. Install GitHub App: Connect your GitHub account
3. Create Project: Link a GitHub repository to a project
4. Edit Content: Use the MDX/Markdown editor to modify files
5. Commit Changes: Save changes directly to your repository

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License.

🔗 Links

• Documentation
• GitHub Repository
• Twitter

💬 Support

For support, please open an issue on GitHub or contact us via email.

---

Built with ❤️ using Astro