Getting Started

Getting Started

The browser path: start the admin against an empty database and it walks you through setup — first admin account, site identity, optional example content — no CLI needed beyond installing and serving (#128).

Requirements

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

Install

Sardine CMS is on PyPI (sardine-cms-*, ADR-0014):

pip install sardine-cms-cli                  # the cms command (pulls core, validation, build)
pip install sardine-cms-theme-ph7x-reference # the reference theme
pip install sardine-cms-admin                # the browser admin (optional)

Database engines beyond SQLite are extras of the core package: pip install "sardine-cms-core[postgres]" (psycopg 3), [mysql] (PyMySQL) or [mssql] (pymssql).

To work on the framework itself, install from source instead:

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/* apps/admin; do pip install -e "$pkg"; done

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.