jchristn77/mincms-server repository overview

⁠MinCMS

MinCMS is a minimal, self-hosted content management system backed by S3-compatible storage. Upload, organize, and share files through a clean REST API and a modern React dashboard — no traditional database required.

MinCMS stores everything (files and metadata) in any S3-compatible bucket — AWS S3, Less3, MinIO, Wasabi, Backblaze B2, and more — so you keep full control of your data.

⁠Why MinCMS?

• Simple by design — no database, no complex setup, just S3 and go
• S3-compatible — works with AWS S3, MinIO, Wasabi, Backblaze B2, and any S3-compatible provider
• Public download pages — share collections of files via clean, browsable URLs
• API-first — every operation is available through a straightforward REST API
• Modern dashboard — manage collections and files through a responsive React UI with light/dark mode
• Docker-ready — up and running in minutes with Docker Compose
• Multi-platform — images available for linux/amd64 and linux/arm64

⁠Use Cases

• File distribution — share downloads, release artifacts, or media assets with public-facing download pages
• Content management — organize files into collections for different projects, teams, or clients
• Digital asset management — centralize images, documents, and media with metadata tracking
• Self-hosted file sharing — a lightweight alternative to heavier CMS platforms when all you need is file management
• Headless CMS backend — use the REST API to serve content to websites, apps, or CI/CD pipelines

⁠Getting Started

⁠Prerequisites

• Docker⁠ and Docker Compose⁠
• An S3-compatible storage account (AWS S3, MinIO, Wasabi, etc.)

⁠Quick Start with Docker Compose

1. Clone the repository

   git clone https://github.com/jchristn/MinCMS.git
   cd MinCMS/docker
   

   Copy

2. Configure your S3 credentials (required before starting)

   Edit docker/server/mincms.json and fill in your S3 settings. The server will fail to start if these are not configured.

   AWS S3:

   {
     "S3": {
       "AccessKey": "your-access-key",
       "SecretKey": "your-secret-key",
       "Bucket": "your-bucket-name",
       "Region": "us-east-1"
     }
   }
   

   Copy

   MinIO or other S3-compatible services — also set EndpointUrl and RequestStyle:

   {
     "S3": {
       "AccessKey": "minioadmin",
       "SecretKey": "minioadmin",
       "Bucket": "my-bucket",
       "Region": "us-east-1",
       "EndpointUrl": "http://localhost:9000",
       "UseSsl": false,
       "RequestStyle": "PathStyle"
     }
   }
   

   Copy

   Important: You must update docker/server/mincms.json with valid S3 credentials before running docker compose up. The configuration file is mounted into the container at startup — changes made after the container is running require a restart (docker compose restart mincms-server).

3. Start the stack

   docker compose up -d
   

   Copy

4. Access the services

   Service	URL
   API	http://localhost:8200⁠
   Dashboard	http://localhost:8300⁠

5. Log into the dashboard using the default API key: mincmsadmin

⁠Architecture

MinCMS consists of two services:

All data — both file content and collection metadata — is stored in your S3 bucket. There is no separate database to manage, back up, or migrate.

┌──────────────┐      ┌──────────────┐      ┌──────────────────┐
│   Dashboard  │────> │  API Server  │────> │  S3-Compatible   │
│  (React 19)  │      │  (.NET 10)   │      │     Storage      │
└──────────────┘      └──────────────┘      └──────────────────┘
     :8300                :8200              AWS / Less3 / MinIO

⁠API Overview

All API endpoints (except health checks and public downloads) require authentication via x-api-key header or Authorization: Bearer <key>.

⁠Collections

⁠Files

⁠Public Downloads (No Authentication)

⁠Configuration

MinCMS is configured through mincms.json and environment variables. Environment variables take precedence, making it easy to override settings per deployment.

⁠Settings File (mincms.json)

{
  "Rest": {
    "Hostname": "localhost",
    "Port": 8200,
    "Ssl": false
  },
  "S3": {
    "AccessKey": "",
    "SecretKey": "",
    "Bucket": "",
    "Region": "",
    "EndpointUrl": null,
    "UseSsl": true,
    "RequestStyle": "VirtualHosted"
  },
  "AccessKeys": [
    {
      "Name": "Admin",
      "Key": "mincmsadmin"
    }
  ],
  "Logging": {
    "ConsoleLogging": true,
    "MinimumSeverity": 1,
    "EnableColors": false,
    "FileLogging": true,
    "LogDirectory": "./logs/",
    "LogFilename": "mincms.log",
    "IncludeDateInFilename": true,
    "Servers": []
  }
}

⁠Server Environment Variables

⁠Dashboard Environment Variables

⁠Configuration Precedence

Environment variable (if set and non-empty)
  └─ overrides → mincms.json value
                   └─ overrides → built-in default

⁠Building from Source

⁠Server

cd src/MinCms.Server
dotnet build
dotnet run

⁠Dashboard

cd dashboard
npm install
npm run dev

⁠Docker Images

Multi-platform images (linux/amd64 and linux/arm64) can be built with the provided scripts:

build-server.bat v0.1.0
build-dashboard.bat v0.1.0

⁠Contributing

Contributions are welcome! Here's how to get involved:

• Report bugs — open an issue on the Issues⁠ tab
• Request features — open an issue describing your idea
• Ask questions — start a thread in the Discussions⁠ tab
• Submit a PR — fork the repo, make your changes, and open a pull request

⁠License

MinCMS is released under the MIT License⁠. You are free to use, modify, and distribute it.

⁠Version History

See CHANGELOG.md⁠ for release notes.