Getting Started

Getting Started

Requirements

• Python 3.12+ (3.12 and 3.13 are tested in CI)
• Git

Install

Sardine CMS is a monorepo of installable packages. The distributions are named sardine-cms-* (ADR-0014) and publish to PyPI on version tags; until the first tag lands, install from source:

git clone https://github.com/ph7x-Systems/sardine-cms.git
cd sardine-cms
python -m venv .venv && source .venv/bin/activate
for pkg in packages/cms-core packages/cms-validation packages/cms-build \
           packages/cms-theme-ph7x-reference packages/cms-cli; do
  pip install -e "$pkg"
done
# optional: the admin panel
pip install -e apps/admin

Create a project

cms init my-site --name "My Site" --base-url "https://my-site.example"
cd my-site

cms init scaffolds a project directory with a sardine.toml, a media folder and an empty SQLite content database. See Configuration for every key.

Seed, validate, build

cms seed        # fictional starter content (Sardine Aerospace), 5 languages
cms validate    # language parity, slugs, media references, alt coverage
cms build       # deterministic static site into _site/
cms preview     # serve _site/ locally on port 8000

cms seed refuses to overwrite a non-empty database (exit code 3); pass --force to replace existing content deliberately.

Export for a host

cms export --target swa      # Azure Static Web Apps (adds staticwebapp.config.json)
cms export --target nginx    # nginx config + container-ready layout
cms export --target generic  # plain static files (default)

Run the admin (optional)

cms admin create-user editor-in-chief --role admin   # prompts for a password
SARDINE_STORAGE_URL="sqlite:///content.sqlite3" \
SARDINE_ADMIN_COOKIE_SECURE=0 \
  uvicorn --factory cms_admin.app:create_app

Then sign in at http://127.0.0.1:8000/login. There are no default credentials — the first account always comes from the CLI. See Admin Panel.

The full loop

1. Edit content in the admin (or via the Python API).
2. cms validate — the publish gate; errors block publishing.
3. cms build — same input, byte-identical output.
4. cms export --target … and deploy the _site/ folder anywhere static files are served.