Ceox

Getting started

This guide walks you through starting a new project on the CEOX Foundation — from an empty machine to a running app and a green quality gate. The framework is a universal Django 6 + HTMX + Tabler starter: server-rendered, secure by default, bilingual, with a built-in onboarding stack (registration, Google login, email 2FA, Stripe subscriptions, invoicing).

But the framework is more than a Django starter: it is built for agent-driven development. The repository ships a full Claude Code integration (a startup contract, a rulebook, guarding hooks, slash commands, and an MCP server that serves a Tabler catalog) that steers the agent toward the framework's principles and blocks the most common mistakes with machine gates. That is why this guide begins with section 0 — setting up Claude Code — and only then moves on to installing the Django project.

If you only care about the classic install, jump to 1. Prerequisites. If you work with an agent (Claude Code), read 0. and the MCP section first.

0. Setting up Claude Code (the agent environment)

Claude Code is the CLI-based agent environment you use to develop the framework. The repo is arranged so that the agent works by the framework's rules from the very first moment.

0.1 Prerequisites for Claude Code

0.2 The repo's Claude Code integration

0.4 The guarding hooks (what they block)

.claude/settings.json wires up four hooks; the hook scripts live under tools/ (check_frozen.py directly, the rest under tools/hooks/), there is no .claude/hooks/ folder. These are defense-in-depth, not a sandbox — they enforce the framework's principles mechanically:

The settings.json permission list also carries deny entries: reading/writing .env*, *.pem, *.key, vendor_src/**, static/vendor/** and the generated catalog JSON(L) is forbidden. So don't try to write into the vendor or a frozen module from the shell, or read .env — the right path is the Edit/Write tool and the named tools/ scripts.

0.5 Slash commands (the module lifecycle)

The commands under .claude/commands/ carry development through:

/bootstrap  ->  /module-plan  ->  (approval)  ->  /module-build
            ->  /module-review  ->  commit  ->  /module-close

MCP servers: what they are for and what to watch

Claude Code gets two MCP servers from .mcp.json. They complement the repo's own documentation, they do not replace it.

The two servers

The tabler tools:

Publishing a plugin runtime into static/vendor is CLI-only, not an MCP tool: run python tools/tabler_publish.py --ref <ref> (or --lib <name>); only a local (vaulted) plugin is published, never from a CDN, and the deploy runs the same step. The MCP surface stays read-only (2027 audit: the redundant materialize writing tool was removed from MCP).

What to watch during INSTALL

What to watch during DEVELOPMENT

The order of the daily frontend session:

  1. Approved component FIRST — from templates/components/ and /styleguide/. We do not invent UI.
  2. Search — tabler_search(...) → stable ref (Hungarian works too; kind="icon" narrows).
  3. Extract — tabler_component("<ref>") → balanced markup + exact dependencies + the HTMX contract; icon {% tabler_icon "name" %}.
  4. Plugin if needed — python tools/tabler_publish.py --ref <ref> (CLI-only) for the required runtime only.
  5. Build a Django/HTMX-compatible component — the authoritative logic stays in Django; don't copy the markup blindly, push it into components/ and the styleguide.

Two common pitfalls:

1. Prerequisites

cloud-sql-proxy ceox-hu-1:europe-west4:ceox-db --port 5433 --auto-iam-authn

2. Configure access (.env)

Copy the template and fill in the values:

cp .env.example .env

.env is never committed. Every setting is documented inline in .env.example, including units where they aren't obvious. Turn features on only as you need them with the USE_* switches — the preflight checks only the keys of the features you enabled.

Worth knowing:

3. Install

make install

This is pip install -e ".[dev]" (which pulls in the dev dependencies, including mcp[cli] and Playwright) + playwright install chromium (needs network).

Then verify the required external access is in place:

make preflight

A non-zero exit tells you exactly which access is missing — stop and fix it before moving on.

Installation pitfalls

4. Database

For local development SQLite is the default (zero setup). To develop against PostgreSQL, start the Cloud SQL Proxy on port 5433 and set DEV_USE_POSTGRES=1 in .env.

Create the schema and seed the three example plans (Free / Starter / Pro):

python manage.py migrate

Create an admin user:

python manage.py createsuperuser

If you use Stripe, create the test products and monthly prices (idempotent — a stable lookup_key means no duplicates, and it runs only for paid plans):

python manage.py setup_stripe_plans

5. Translations

The UI is exactly bilingual (English + the project language, default Hungarian), with English msgids. Mixed language is forbidden: if you add, delete or rename visible text, updating the catalog is mandatory — otherwise, in a Hungarian browser, untranslated (and fuzzy!) text renders in English.

The full cycle after a text change:

python manage.py makemessages -l hu -l en    # or: make messages
python manage.py i18n_todo                    # shows missing and fuzzy entries
python manage.py compilemessages              # or: make messages-compile

The .mo is loaded at startup, so after compilemessages restart the dev server.

6. Run

make run

The app is at http://127.0.0.1:8000. The landing page, sign-in, registration, dashboard and the component gallery (/styleguide/ in dev) are all live.

Development golden rules

The framework's machine gates (the frontend-boundary checker, system checks, hooks) enforce these too — worth keeping in mind before the checker turns red:

7. Quality gate

Before every commit:

make gate         # lint + frontend boundary + migration drift + tests & coverage
make gate-full    # the above + static build + Playwright end-to-end

Do not commit on a red gate. Push to main only after a green gate; no force push, no unchecked reset --hard; before committing, review the staged diff and check there's no secret in it. (The commit-gate hook enforces this mechanically too.) On Windows run make from Git Bash.

Deploy (going to production)

The framework offers a one-command deploy. The target comes from deploy/targets.json (parameterizable instance), and the process ends with a readiness gate + automatic rollback.

make ship                     # to the 'production' target
make ship TARGET=staging      # another instance (just a different --target)
make ship M="what I changed"  # if there are uncommitted changes (commit + push + deploy)

This runs the python tools/deploy.py --target production ... chain:

  1. Quality gate: runs make gate; if red, the deploy stops (--no-gate can disable it, but that's not recommended).
  2. Commit (if dirty and -m given) + push to origin main; records the HEAD SHA.
  3. Deploy over an IAP tunnel: on the VM a ROOT-owned deploy wrapper (outside the repo) installs the exact commit (no key in the script, and the firewall need not open port 22).

Copy targets.json from deploy/targets.example.json (gitignored) and parameterize it with the instance/zone/GCP-project/app values. Another instance = just another entry + --target.

The VM-side wrapper steps: mandatory precondition check → deploy lock (flock, no concurrent deploy) → detached checkout to the expected SHA → dependencies from the lock → check --deploy → migrate → collectstatic (with production settings) → systemctl restart → readiness gate (querying /health/ready/ directly on the gunicorn unix socket, every 2 s, for 60 s total). If there's no 200, an automatic code rollback to the previous commit. A failure in any step after checkout triggers the same rollback.

Important: the rollback is code-level — it does NOT undo migrations that already ran. So keep migrations backward-compatible (additive first; deletion/tightening only in a later release).

8. Make it your own

That's it — you now have a running, tested, production-shaped starter to build your product on, and an agent environment that holds itself to the framework's principles.

We use essential cookies (session, CSRF, language) to run the site. With your consent we also use analytics to improve it — you can decline. Cookie details in the Privacy Policy.