A modern, secure flat-file CMS built with Node.js that manages content using Markdown files. Features a powerful admin panel, REST API, search functionality, and comprehensive security measures suitable for production deployment.
- Flat-File Architecture: No database required - content stored as Markdown files
- Dynamic Routing: Automatic URL mapping from file structure
- Markdown Support: Full GitHub Flavored Markdown with frontmatter metadata
- Template System: Flexible Handlebars templates with inheritance
- Admin Panel: Modern, responsive admin interface with Bulma CSS
- File Management: Upload and manage media files with image processing
- Full-Text Search: Intelligent search with relevance scoring and suggestions
- REST API: Complete headless CMS API for external integrations
- Plugin System: Extensible architecture with hooks and filters
- Caching: Smart content caching for improved performance
- Security: Production-ready security with rate limiting and validation
- Multi-Tier Rate Limiting: DDoS protection with configurable limits
- Security Headers: Comprehensive headers via Helmet.js (CSP, HSTS, etc.)
- Input Validation: Server-side validation and sanitization
- CSRF Protection: Form security with token validation
- File Upload Security: MIME type restrictions and size limits
- Authentication: Secure bcrypt password hashing with sessions
- Node.js: 16.x or higher
- npm: 8.x or higher
- Memory: 256MB RAM minimum (512MB recommended)
- Storage: 100MB free space (lightweight like Kirby CMS)
- Operating System: Linux, macOS, or Windows
For production servers, use our automated deployment script:
# One-click deployment to VPS/server (no Docker required)
curl -fsSL https://raw.githubusercontent.com/audit-brands/stack_blog/main/scripts/deploy-simple.sh | bashThis script automatically:
- ✅ Checks system requirements and installs dependencies
- ✅ Creates secure environment configuration
- ✅ Sets up systemd service and Nginx reverse proxy
- ✅ Configures logging, backups, and firewall
After deployment: Run sudo -u stackblog node /home/stackblog/stack_blog/scripts/setup.js for interactive setup.
See Deployment Guide for detailed instructions.
-
Clone the repository
git clone https://github.com/audit-brands/stack_blog.git cd stack_blog -
Install dependencies
npm install
-
Set up environment variables
cp .env.example .env # Edit .env with your configuration -
Generate admin password hash
npm run setup # Follow prompts to create admin password -
Start the server
npm start
-
Access your site
- Frontend: http://localhost:3000
- Admin Panel: http://localhost:3000/admin
Create a .env file in the root directory:
# Application Settings
NODE_ENV=development
PORT=3000
# Security Configuration
SESSION_SECRET=your-secure-session-secret-here
API_KEY=your-secure-api-key-here
ADMIN_PASSWORD_HASH=your-bcrypt-password-hash-here
# CORS Configuration
ALLOWED_ORIGINS=http://localhost:3000,https://yourdomain.com
# Content Configuration
CONTENT_PATH=./content
MEDIA_PATH=./media
CACHE_TTL=300000- Installation Guide - Comprehensive installation instructions for all deployment methods
- API Documentation - REST API reference and examples
- Security Guide - Security features and best practices
- Security Audit - Comprehensive security assessment
- Deployment Guide - Production deployment instructions
- Development Guide - Contributing and development setup
- Configuration - Environment variables and settings
- Plugin Development - Creating custom plugins
- Template System - Template development guide
- Content Management - Content creation and organization
stack_blog/
├── app.js # Main application entry point
├── config/ # Configuration files
├── content/ # Markdown content files
├── docs/ # Documentation
├── middleware/ # Express middleware
├── plugins/ # Plugin directory
├── public/ # Static assets (CSS, JS, images)
├── routes/ # Express route handlers
├── services/ # Business logic services
├── views/ # Handlebars templates
└── __tests__/ # Test files
- ContentService: Manages Markdown file operations
- AuthService: Handles authentication and sessions
- MediaService: File upload and image processing
- SearchService: Full-text search and indexing
- CacheService: Content caching and performance
- PluginService: Plugin management and hooks
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run specific test file
npm test ContentService.test.js# Start development server with hot reload
npm run dev
# Run linting
npm run lint
# Run security audit
npm audit
# Generate password hash for admin
npm run setupContent is stored as Markdown files in the content/ directory:
---
title: "Your Page Title"
description: "Page description for SEO"
template: "default"
date: "2024-01-01"
---
# Your Content Here
Write your content in **Markdown** format.content/
├── index.md # Homepage
├── about/
│ └── index.md # About page
├── blog/
│ ├── post-1.md # Blog post
│ └── post-2.md # Another blog post
└── media/ # Uploaded media files
# Set API key in headers for protected endpoints
curl -H "Authorization: Bearer your-api-key" \
-H "Content-Type: application/json" \
http://localhost:3000/api/pages# Get all pages
GET /api/pages
# Get specific page
GET /api/pages/:slug
# Create new page
POST /api/pages
{
"title": "New Page",
"content": "# Content here",
"description": "Page description"
}
# Search content
GET /api/search?q=keywordSee API Documentation for complete reference.
Stack Blog implements comprehensive security measures:
- Configure strong session secrets
- Set up HTTPS with valid SSL certificates
- Configure rate limiting for your traffic patterns
- Set up proper CORS origins
- Enable security headers
- Configure firewall rules
- Set up log monitoring
- Regular dependency updates
- Rate Limiting: Multi-tier protection against abuse
- Input Validation: All user inputs validated and sanitized
- Security Headers: CSP, HSTS, XSS protection, and more
- File Upload Security: MIME type restrictions and scanning
- CSRF Protection: Form submissions protected with tokens
- Session Security: HTTPOnly cookies with secure flags
See Security Guide for detailed information.
# Build and run with Docker
docker build -t stack-blog .
docker run -p 3000:3000 --env-file .env stack-blog# Install dependencies
npm ci --production
# Set environment to production
export NODE_ENV=production
# Start with PM2
npm install -g pm2
pm2 start ecosystem.config.jsserver {
listen 80;
server_name yourdomain.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}See Deployment Guide for complete instructions.
Create custom plugins to extend Stack Blog:
// plugins/my-plugin/index.js
module.exports = {
name: 'my-plugin',
version: '1.0.0',
hooks: {
'content:before-render': (content) => {
// Modify content before rendering
return content;
}
}
};See Plugin Development Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Open a Pull Request
- Write tests for new features
- Follow existing code style
- Update documentation
- Ensure security best practices
This project is licensed under the ISC License - see the LICENSE file for details.
- Documentation: Check the
docs/directory - Issues: Report bugs on GitHub Issues
- Security: See Security Guide for security reporting
- Built with Express.js and Node.js
- Templates powered by Handlebars
- Styling with Bulma CSS
- Security provided by Helmet.js
- Markdown processing by markdown-it
Stack Blog - A modern, secure flat-file CMS for the Node.js ecosystem.