🚧 v0 · early access — not for production🚧 FastCMS is under active development — not ready for production use. APIs and features may change without notice.
FastCMS
Getting Started

Installation & Setup

Install FastCMS and get your server running in minutes.

Installation & Setup

FastCMS uses uv — the fast modern Python toolchain — as its recommended installer. uv handles Python versions, virtual environments, and packages with one command.

Prerequisites

Install uv (one-time, ~5 seconds):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

uv handles Python itself — you don't need to install Python 3.11+ separately.

# Install FastCMS as a global CLI (auto-isolated)
uv tool install pyfastcms

# Create a new project
fastcms init my-project
cd my-project

# Set up the database
fastcms migrate up

# Create an admin user
fastcms create-admin

# Start the development server
fastcms dev

The fastcms init command scaffolds a complete project with .env (auto-generated SECRET_KEY), database migrations, and directories for plugins and hooks.

Option 2: Project-local with uv add

Use this if FastCMS will be a dependency of your own application:

uv init my-app
cd my-app
uv add pyfastcms

# All fastcms commands now run via `uv run`
uv run fastcms migrate up
uv run fastcms create-admin
uv run fastcms dev

Option 3: From Source (Contributors)

For contributing to FastCMS or running from the repository directly:

# Clone the repository
git clone https://github.com/aalhommada/fastCMS.git
cd fastCMS

# uv sync creates .venv, installs everything (dev tools included)
uv sync --all-extras
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Set up the database and start
fastcms migrate up
fastcms create-admin
fastcms dev

Option 4: Docker (production-grade stack)

For Postgres + Redis + FastCMS in one command:

git clone https://github.com/aalhommada/fastCMS.git
cd fastCMS
cp .env.example .env       # set SECRET_KEY (openssl rand -hex 32) inside
docker compose up -d

See the full Docker deployment guide for configuration, persistence, reverse proxy setup, and scaling notes.

Add plugins (optional)

FastCMS keeps the core install lightweight. Features like AI, vector search, RAG, and autonomous agents ship as separate plugins — install only what you need:

fastcms plugin install ai-core      # LLM provider abstraction
fastcms plugin install ai-vectors   # semantic search
fastcms plugin install ai-rag       # Q&A on your docs
fastcms plugin install ai-agents    # autonomous agents

Plugins load at server start, so restart fastcms dev after installing one. Full plugin reference: Plugin System.

Using pip instead

uv is recommended but pip works too. Just make sure you're inside an active virtualenv first:

python -m venv .venv
source .venv/bin/activate
pip install pyfastcms

Access the Admin Dashboard

Navigate to http://localhost:8000/admin in your browser.

localhost:8000/admin/login

FastCMS Admin Login

admin@fastcms.dev
••••••••••••
Or continue with

OAuth login buttons only work if configured in .env file

After signing in, you land on the main dashboard:

localhost:8000/admin

Dashboard

System overview and statistics

Total Users

142

Admins: 3

New Users (7d)

18

View all users →

Collections

9

Manage collections →

Backups

12

Manage backups →

Files

384

Storage: 1.2 GB

Quick Actions

Manage Users

View, edit, and manage user accounts

Manage Collections

View and manage collections

API Documentation

View API docs and test endpoints

Recent Backups

backup_2026-03-04_09-00-00.db

4.2 MB

2 hours agoView

backup_2026-03-03_09-00-00.db

4.1 MB

1 day agoView

Environment Variables

Create a .env file in the project root:

# Application
ENV=development
DEBUG=true

# Database
DATABASE_URL=sqlite:///./data/app.db

# Security
SECRET_KEY=your-secret-key-here-change-in-production
ACCESS_TOKEN_EXPIRE_MINUTES=1440
REFRESH_TOKEN_EXPIRE_DAYS=7

# CORS
CORS_ORIGINS=http://localhost:3000,http://localhost:8000

Database

FastCMS uses SQLite with WAL (Write-Ahead Logging) mode for better concurrency.

Database Location: data/app.db

Important Notes:

  • All collections are stored as dynamic tables
  • The collections table stores metadata and schemas
  • The users table is for admin authentication only
  • Auth collections create their own tables with authentication fields

Interactive API Documentation

FastCMS provides interactive API documentation powered by Swagger UI.

Access it at: http://localhost:8000/docs

This interface allows you to:

  • Browse all available endpoints
  • Test API calls directly from the browser
  • View request/response schemas
  • Authenticate and test protected endpoints

Best Practices

Security

  1. Always use strong SECRET_KEY in production
  2. Use HTTPS in production
  3. Set appropriate access control rules on collections
  4. Validate user input on the client side
  5. Use refresh tokens for long-lived sessions

Performance

  1. Add indexes to frequently queried fields
  2. Use pagination for large datasets
  3. Set appropriate cache TTL for view collections
  4. Use view collections for complex queries instead of client-side joins

Data Modeling

  1. Use auth collections for any user type requiring authentication
  2. Use base collections for standard data
  3. Use view collections for reports and aggregations
  4. Use relation fields to link collections
  5. Set cascade_delete appropriately on relations

Troubleshooting

Collection Creation Fails

Issue: "An invalid form control with name='' is not focusable"

Solution: This occurs when hidden required fields (relation/view fields) are present. Ensure you're creating the correct collection type and all visible required fields are filled.

Authentication Fails

Issue: 401 Unauthorized

Solution:

  • Ensure access token is included in Authorization header
  • Check if token has expired (access tokens expire in 15 minutes by default)
  • Use refresh token to get a new access token

Access Denied to Records

Issue: Cannot view/edit records despite being authenticated

Solution:

  • Check the access control rules on the collection
  • Ensure your user meets the rule criteria
  • Verify the record data matches the rules (e.g., user_id field)

Next Steps

Introduction

FastCMS is a production-ready Backend-as-a-Service built with FastAPI and Python — your open-source alternative to Supabase and PocketBase.

Command Line Interface

Manage FastCMS from the terminal — create users, collections, run migrations, and start the dev server.

On this page

Installation & SetupPrerequisitesOption 1: Install from PyPI (Recommended)Option 2: Project-local with uv addOption 3: From Source (Contributors)Option 4: Docker (production-grade stack)Add plugins (optional)Using pip insteadAccess the Admin DashboardEnvironment VariablesDatabaseInteractive API DocumentationBest PracticesSecurityPerformanceData ModelingTroubleshootingCollection Creation FailsAuthentication FailsAccess Denied to RecordsNext Steps