ital8cms

Modular, plugin-based Content Management System built on Node.js and Koa.js

• Version: 0.0.1-alpha.0 (Early Alpha)
• Author: Italo Paesano (italopaesano@protonmail.com)
• License: ISC

Core Philosophy

Zero Database Dependency - ital8cms does not require any DBMS by default. The core system uses JSON files for structured data storage and file-based storage for content. Database systems like SQLite are optional and can be added through plugins when needed.

Developer-First Approach - This CMS is designed for developers who understand HTML, CSS, JavaScript, EJS templating, and Node.js. No drag-and-drop interfaces - all customization is done through code and configuration files.

Key Features

• Plugin-based architecture with dynamic loading and dependency resolution
• Plugin Pages System - auto-served public pages with zero configuration
• File-based storage - no database installation required
• JSON5 configuration with comments and trailing commas support
• Modular theme system with EJS templates and automatic customization injection
• Modern stack - Koa v3.2.0, Node.js >=22.13
• Session-based authentication with RBAC
• Bootstrap 5.3 integration

Quick Start

# Install dependencies
npm install

# Start development server
npm start

Server runs on: http://localhost:3000

Documentation

For Developers & AI Assistants

• CLAUDE.md - Complete guide for AI assistants and developers (root)

docs/archive/ - Materiale archiviato (storico / spunto):

• Coding style - guida allo stile (obsoleta, spunto)
• Koa v3 migration - migrazione storica (archiviata)

Project Documentation

• Panoramica documentazione - panoramica storica (archiviata; vedi CLAUDE.md e docs/)
• CLI control plane - pilotare un'istanza in esecuzione da terminale/SSH con ital8cms-cli (npm run cli -- …): attivare/disattivare l'area admin, manutenzione del sito pubblico, chiusura della superficie riservata (assetto "sito vetrina"), reset config, migrazioni dei config

Technology Stack

Backend:

• Koa.js v3.2.0 (web framework)
• EJS v6.0.1 (templating)
• JSON5 v2.2.3 (config with comments)
• bcryptjs v3.0.3 (authentication)
• Bootstrap v5.3.8 (UI)

Optional:

• better-sqlite3 (SQLite database via dbApi plugin)
• ccxt v4.1.70 (cryptocurrency exchanges via ccxt plugin)

Plugin System

ital8cms features a sophisticated plugin system:

• Dynamic loading with dependency resolution
• Inter-plugin communication via shared objects
• Lifecycle hooks (load, install, uninstall, upgrade)
• Middleware registration
• Custom API routes with automatic prefixing
• Page hooks for content injection

Plugin Structure

Minimum required:

plugins/myPlugin/
├── main.js                    # Plugin logic (required)
├── pluginConfig.json5         # Configuration (required)
└── pluginDescription.json5    # Metadata (required)

Recommended for plugins serving web pages:

plugins/myPlugin/
├── main.js
├── pluginConfig.json5
├── pluginDescription.json5
└── webPages/                  # ⭐ Strongly recommended for EJS templates
    ├── login.ejs
    ├── profile.ejs
    └── settings.ejs

The webPages/ directory is a strongly recommended convention for organizing EJS templates in plugins that serve HTML pages. It provides clear separation between logic and presentation, and follows the pattern used in the adminUsers reference plugin.

Theme System

Modular theme system with composable EJS partials:

themes/myTheme/
├── views/              # Reusable partials
│   ├── head.ejs
│   ├── header.ejs
│   ├── nav.ejs
│   ├── main.ejs
│   ├── aside.ejs
│   └── footer.ejs
└── templates/          # Complete page templates

Data Storage

Primary: JSON5 files

• User accounts: plugins/adminUsers/userAccount.json5
• User roles: plugins/adminUsers/userRole.json5
• Plugin configs: */pluginConfig.json5

Optional: SQLite database via dbApi plugin (currently disabled)

Authentication

Session-based authentication with role-based access control (RBAC):

• Roles: root (0), admin (1), editor (2), viewer (3)
• Protected paths: /reserved, /private, /lib
• Admin panel: /admin (requires authentication)

Project Structure

ital8cms/
├── index.js              # Application entry point
├── ital8Config.json5       # Main configuration
├── CLAUDE.md             # AI assistant guide
├── core/                 # Core CMS functionality
├── plugins/              # Plugin modules
├── themes/               # Theme templates
├── www/                  # Public web root
└── docs/                # Documentazione (standard ital8doc, guide, archivio)

Development

# Start with auto-reload (development)
npm run dev

# Start without auto-reload (production)
npm start

# Run tests
npm test

# Enable optional SQLite database
# 1. Edit plugins/dbApi/pluginConfig.json5: "active": 1
# 2. npm install better-sqlite3
# 3. Restart server

Operating a running instance (CLI control plane)

Drive a running instance from the terminal over a local UNIX socket — the usual way to do it over SSH. Full guide: docs/cli-control-plane.it.md.

npm run cli -- status          # pid, uptime, ports, admin/reserved/public state
npm run cli -- admin stop      # disable the admin area (restarts the process)
npm run cli -- admin start     # enable it again
npm run cli -- public stop     # public site in maintenance (503, no restart)
npm run cli -- public start    # public site back online
npm run cli -- reserved stop   # everything behind auth (login, admin panel): 404, no restart
npm run cli -- reserved start  # reserved surface reachable again
npm run cli -- publicOnly on   # showcase layout: reserved stop + admin stop (restarts)
npm run cli -- publicOnly off  # back to the normal layout
npm run cli -- reset <target>  # plugin/theme configs back to defaults
npm run cli -- migrate <target> # apply pending config migrations (--dry-run)

Keep the --: with npm run, positional arguments are forwarded but flags (--json, --theme, …) are swallowed by npm without any error. The global ital8cms-cli binary only exists after npm link or npm install -g ..

License

ISC License - See package.json for details

Author

Italo Paesano

• Email: italopaesano@protonmail.com
• GitHub: @italopaesano

---

Note: This project is in early alpha (v0.0.1-alpha.0). APIs and architecture may change.