ForgeCMS

ForgeCMS is a Flask-based blogging and CMS application backed by MariaDB. It includes authentication, an admin workflow for draft/scheduled/published content, Markdown authoring, and media upload support.

Overview

What ForgeCMS provides

• User registration and login
• Admin content management experience
• Post workflow states (draft, scheduled, published, archived)
• Preview support for unpublished posts
• SEO-friendly slugs and Bootstrap-based responsive UI
• Image upload support for post media

Repository layout

• app/ – Flask application package (blueprints, models, app factory)
• templates/ – Jinja2 HTML templates
• static/ – CSS and uploaded/static assets
• migrations/ – Database migration artifacts (including migrations/manual/ SQL files)
• wsgi.py – WSGI entrypoint
• Dockerfile – Production image definition
• docker-compose.yml – Default single-server deployment
• docker-compose.enterprise.yml – Enterprise multi-instance deployment
• docker/ – Container helper scripts and NGINX configuration

Tech stack

• Python 3.8+
• Flask
• SQLAlchemy + Flask-Migrate
• MariaDB 10.5+
• Bootstrap 5
• Docker / Docker Compose

Quick start with Docker (recommended)

Prerequisites

• Docker Engine 24+
• Docker Compose v2+

1) Configure environment

cp .env.example .env

Update at least:

• SECRET_KEY
• DB_PASSWORD
• DB_ROOT_PASSWORD

2) Default mode: single Linux server

Runs one ForgeCMS container plus one MariaDB container on one host.

docker compose up -d --build

• ForgeCMS: http://localhost:8000
• Persistent data:
  • mariadb_data volume for DB
  • uploads_data volume for media uploads

Stop:

docker compose down

3) Enterprise mode: multi-instance application tier

Runs two ForgeCMS app instances behind NGINX plus one MariaDB server.

docker compose -f docker-compose.enterprise.yml up -d --build

• Entry point: http://localhost (port 80)
• Backend app containers: forgecms-a, forgecms-b
• Shared uploads volume mounted by both app containers and NGINX

Stop:

docker compose -f docker-compose.enterprise.yml down

Docker behavior notes

• Container startup waits for MariaDB before launching the app.
• Database migrations run automatically at startup.
  • In enterprise mode, only forgecms-a runs migrations.
• UPLOAD_FOLDER defaults to static/uploads and is persisted in Docker volumes.

Local non-Docker setup

1) Clone the repository

git clone <repository-url>
cd forgecms

2) Create and activate a virtual environment

python -m venv venv
# Linux/macOS
source venv/bin/activate

3) Install dependencies

pip install -r requirements.txt

4) Create MariaDB database and user

CREATE DATABASE forgecms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'forgecms'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON forgecms.* TO 'forgecms'@'localhost';
FLUSH PRIVILEGES;

5) Configure environment variables

cp .env.example .env

6) Apply database migrations

flask db upgrade

7) Run the development server

flask run

By default, Flask serves on http://127.0.0.1:5000.

Create an admin user (Flask shell)

flask shell

from app import db
from app.models import User

admin = User(username='admin', email='admin@example.com', is_admin=True)
admin.set_password('your-secure-password')
db.session.add(admin)
db.session.commit()

Community and governance

• Contributing guide
• Code of Conduct
• License (GNU GPLv3)