documentation

DotNetForge CMS

A modular, secure, lightweight hybrid CMS built on ASP.NET Core MVC (C#, EF Core, Razor), targeting .NET 10, with SQLite (default) and PostgreSQL support. It runs as a Traditional CMS (visual admin), a Headless CMS (token-secured API), or both at once (Hybrid) over the same content.

Product goals and scope: .docs/product.md. The technical documentation - architecture, every screen, every feature, verified against the code - starts at .docs/README.md; what is built versus planned is in .docs/implementation-status.md.

Requirements

• .NET SDK 10.0 (pinned via global.json).
• Optionally PostgreSQL if you don't use the default SQLite provider.

Quick start

# 1. Configure the environment (secrets live in .env, never committed)
cp .env.example .env          # Windows PowerShell: Copy-Item .env.example .env

# 2. Run the web app (from the repository root)
dotnet run --project src/DotNetForge.Web      # or: dotnet watch --project src/DotNetForge.Web

Then open http://localhost:5000. On first run the app redirects to /setup, where you create the first administrator (assigned the Super Admin role). After setup you land on the admin dashboard at /admin; the setup wizard is then permanently blocked.

Optional: docker compose -f docker/compose.dev.yml up -d starts PostgreSQL and an S3-compatible server for developing against production-like backends (development guide).

Production

The app runs from a read-only deployment directory: data goes to PostgreSQL (or SQLite on a volume), uploaded media to S3-compatible object storage (Cloudflare R2 recommended), and the Data Protection key ring to the database.

docker build -f docker/Dockerfile -t dotnetforge .
docker run --read-only --tmpfs /tmp -p 8080:8080 -e DATABASE_PROVIDER=postgresql -e "DATABASE_CONNECTION_STRING=Host=...;Database=..." \
  -e STORAGE_S3_SERVICE_URL=... -e STORAGE_S3_BUCKET=... \
  -e STORAGE_S3_ACCESS_KEY_ID=... -e STORAGE_S3_SECRET_ACCESS_KEY=... dotnetforge

Everything else - environment variables, reverse proxy, backups, verification: deployment guide.

Everyday commands

Run from the repository root. DotNetForge.slnx is the solution, so dotnet build and dotnet test cover every project; the web app is src/DotNetForge.Web.

In VS Code, F5 starts the debugger and Run Build Task offers build, run, watch and test tasks.

Configuration (.env)

Copy .env.example to .env and set the values. Secrets are never committed (see .gitignore).

Outside Development nothing may default into the deployment directory: SQLite needs an absolute path and media needs S3.

Full reference: .docs/features/configuration.md.

Switching to PostgreSQL

DATABASE_PROVIDER=postgresql
DATABASE_CONNECTION_STRING=Host=localhost;Port=5432;Database=dotnetforge;Username=postgres;Password=postgres

SQL Server, MySQL and MongoDB work the same way; examples are in .docs/database/configuration.md.

Both providers apply their committed EF Core migrations on startup; see .docs/architecture/database.md.

Project layout

DotNetForge.slnx         # Solution: every project below
src/
  DotNetForge.Web/       # ASP.NET Core MVC web app: admin area, public site, setup, composition root
  DotNetForge.*/         # Libraries: Abstractions, Shared, Core, Data, Infrastructure, Extensions, Api
tests/                   # DotNetForge.Tests (unit) + DotNetForge.IntegrationTests (integration)
extensions/              # Extensions, by type (themes, plugins, modules, widgets, admin, ...); read-only at runtime
docker/                  # Dockerfile (+ its .dockerignore) and compose.dev.yml for local PostgreSQL + S3
.docs/                   # Technical documentation (start at .docs/README.md), incl. planned work per topic
.github/                 # CI workflow, Dependabot, and AI-agent quick references (.github/agents/)
.claude/skills/          # Claude Code project skills
storage/                 # Development only, git-ignored: local SQLite database and media

See .docs/architecture/overview.md for a one-page architecture summary and .docs/architecture/codebase.md for the responsibilities of each project and folder.

Admin panel (server-rendered Razor)

The admin UI and the first-run setup wizard are server-rendered ASP.NET Core MVC in the src/DotNetForge.Web/Areas/Admin/ area, served at /admin (and /setup for the wizard). No Node build step - it ships with the host; styling is a small hand-rolled stylesheet in src/DotNetForge.Web/wwwroot/css/admin.css. Forms post with antiforgery tokens; the only fetch call is the Content Manager's drag-and-drop reorder (sending the token in an X-CSRF-TOKEN header).

Built screens: Dashboard, Content Manager (page tree + settings + scheduling), Media (upload, download, delete; local or S3-compatible storage), Settings, Users, Roles, Audit Logs, Plugins, API Tokens. Remaining planned areas link to documented placeholders.

Admin extensions are server-rendered too: drop an admin-type manifest with a Views/Index.cshtml under extensions/admin/ and a sidebar tab appears at /admin/ext/{id} (rendered via runtime Razor compilation, isolated in an iframe) with no code changes - see the audit-dashboard sample.

The headless API

As a Super Admin or Admin, create a scoped token from the admin sidebar (Settings · Global Settings → API Tokens; the full secret is shown once), then call the API with a bearer token:

curl -H "Authorization: Bearer <token>" http://localhost:5000/api/content/pages

Every endpoint enforces the token's granular permission (content.read, media.read, ...). Missing authentication returns 401; a missing permission returns 403. Endpoint list: .docs/features/headless-api.md.

Testing & quality

dotnet test tests/DotNetForge.Tests              # unit tests
dotnet test tests/DotNetForge.IntegrationTests   # integration tests (setup, auth, API)
dotnet format --