CodeY CMS

Reusable CMS runtime for websites generated by the CodeY platform.

This repository is intentionally separate from the CodeY platform/control plane. It contains the copied website runtime only: public frontend, /cy-admin, dashboard, CMS pages/posts/media, builder elements, shop modules, Prisma schema, Docker setup, and runtime documentation.

It must not contain the platform app that sells websites, prompt orchestration, AI provider secrets, hosting automation, Cloudflare OAuth tokens, SSH/SFTP credentials, registry secrets, or platform runbooks.

Install CodeY CMS

CodeY CMS is a downloadable, self-hosted CMS. The supported nontechnical path includes PostgreSQL, generated secrets, encrypted backups, the browser installer, and managed stable updates.

1. Install Docker Desktop.
2. Download and extract the latest codey-cms-<version>.zip release.
3. Run start-codey.cmd on Windows or ./start-codey.sh on macOS and Linux.
4. Complete the setup page that opens in your browser.

The launcher generates installation secrets once and keeps them in Docker volumes. Users never choose a CMS version: new installations use the latest certified stable release, while every installed runtime records its exact version for updates and rollback.

Official releases include a signed manifest, immutable container-image references, checksums, and a CycloneDX production-dependency SBOM.

The launcher opens the setup automatically and prints the exact address. Default addresses are:

• Public site: http://localhost:4000
• CMS admin: http://localhost:4000/cy-admin
• Setup, before installation: http://localhost:4000/install

For a public domain, run the same launcher with --domain www.example.com to enable automatic HTTPS. Backup and recovery instructions are in docs/self-host-installation.md.

Local Development

cp .env.example .env
pnpm install
pnpm db:push
pnpm db:seed
pnpm setup:admin
pnpm dev

The default seed creates runtime roles, module settings, and an editable Home page without publishing demo products, posts, coupons, or shipping rules. Set CODEY_SEED_DEMO_CONTENT=true only when you intentionally need sample shop and article data for local testing.

Node.js 24 and pnpm 11 are expected.

Release checks:

pnpm validate
TEST_DATABASE_URL=postgresql://.../codey_cms_test pnpm test:integration
TEST_DATABASE_URL=postgresql://.../codey_cms_test pnpm test:e2e

Integration and browser tests refuse database names that do not contain test, ci, or e2e.

Runtime Shape

• apps/web: public site, CMS dashboard, frontend editor, and builder UI.
• src/modules: auth, users, roles, CMS, localization, media/config, products, orders, notifications, and payments.
• src/core: Express app, API envelope, security middleware, rate limits, and public page routing.
• src/infrastructure: Prisma, email, logging, and storage adapters.
• prisma/schema: base schema plus module schema fragments.
• scripts: schema generation, migrations, seed, admin setup, backup, and restore.

Generator Contract

AI agents should use this repository as the CMS reference when building client websites. Generated work must map content into editable CMS records and registered builder elements, not hard-coded dashboard-only output.

For agent discovery, CodeY CMS includes a read-only MCP server package. It can explain current capabilities, evaluate project fit, return the signed installation workflow, expose the builder registry, and validate WebsiteSpec 1.0 without connecting to customer data.

npx -y codey-cms-mcp

Useful docs:

• docs/ai-agent-integration.md
• docs/generated-site-contract.md
• docs/content-modeling.md
• docs/extensions.md
• docs/module-system.md
• docs/api-contract.md
• docs/runtime-env-contract.md
• docs/self-host-installation.md
• docs/automatic-updates.md
• docs/release-channels.md

Extend CodeY

Custom collections let administrators model reusable content such as people, locations, events, and resources from the dashboard. Declarative extension packs use checksum-pinned catalog verification, drift-safe atomic upgrades, and non-destructive disconnect without executing third-party server code. Atomic content bundles, typed filters, and deterministic sorting give integrations a stable data-portability contract.

pnpm extension:create yourname.extension-name
pnpm extension:catalog
pnpm extension:validate
pnpm extension:validate -- --json extensions/yourname-extension-name

See CONTRIBUTING.md for the contribution workflow, docs/extensions.md for the stable manifest contract, and docs/extension-governance.md for catalog review and maintenance policy.

Safety Boundary

Keep this repository focused on the generated website runtime. Platform-only code belongs in the private CodeY platform repository.

Do not add production secrets, customer credentials, platform tokens, or generated-site private data to this repository.

License

CodeY CMS is free software licensed under the GNU General Public License, version 2 or, at your option, any later version (GPL-2.0-or-later). This is the same open-source licensing model used by WordPress, while CodeY CMS remains a separate project with its own code, identity, and copyright notice.

The software is provided without warranty. CodeY CMS does not claim ownership of user-created content. See LICENSE for the complete license and NOTICE.md for project, third-party, and trademark notices.