Skip to content

README.md

Latest commit

 

History

History
287 lines (228 loc) · 12.6 KB

README.md

File metadata and controls

287 lines (228 loc) · 12.6 KB
Raw

SiteMatrix logo

Stars Forks Last Commit

Tests TDD PHPStan Level 9 Docker Podman WordPress Node License

🚀 Getting Started

git clone https://github.com/barunTayenjam/sitematrix.git
cd sitematrix
chmod +x matrix

# Check your machine is ready — names every missing piece + the exact fix
./matrix doctor

# Start core services: MySQL, Redis, phpMyAdmin, dashboard
./matrix start

# Create your first site (PHP 8.3, port assigned automatically)
./matrix create mysite

Tip

Not sure where to start? ./matrix doctor checks the container runtime, compose tool, ports, .env perms, disk headroom, and DNS — then prints the exact command to fix each failure.

Real session — what a site creation looks like:

$ ./matrix create mysite
✅ Created .env file with generated credentials
✅ Created docker-compose.yml
✅ Created default nginx configuration
✅ Site 'mysite' created successfully with PHP 8.3 (nginx)
✅ Site 'mysite' started and ready!

$ ./matrix ssl mysite --json
{"success":true,"site":"mysite","https_port":9201,"url":"https://localhost:9201",
 "cert_source":"mkcert","fingerprint":"SHA256:9f3c…"}

✨ Features

  • One entry point — every operation is a ./matrix subcommand; the dashboard only invokes it
  • Per-site PHP 7.4 → 8.3 — run legacy and modern sites side by side (--php-version=7.4)
  • Stack-specific provisioning & pinning — --wp-version=6.4|6.5|6.6|latest, then matrix test sweeps them
  • Auto-HTTPS — mkcert (trusted CA) with openssl fallback; TLS on port+1000, <site>.test domains optional
  • Multisite at creation — --multisite=subdirectory|subdomain, nginx/Apache rewrites generated
  • Shareable presets — drop a .sh into config/presets/; --preset=woocommerce just works
  • Client-ready tunnels — matrix share wraps cloudflared/ngrok/bore, one command, Ctrl-C to tear down
  • Portable bundles — export/import a site as tar.gz: manifest + files + sha-verified DB dump
  • Scheduled backups — --schedule=daily --retention=7, marker-block crontab sync
  • Docker and Podman — runtime abstraction everywhere; no docker socket mounted
  • Code quality built in — PHPStan Level 9 + stack-specific standards per site
  • JSON everywhere — every command emits parseable {"success":…}; the dashboard never scrapes text
  • Live dashboard — real-time status, site flyouts, activity log, keyboard shortcuts at :8500
  • Doctor — bootstrap checks that degrade with a fix-command, never a dead end
Why matrix? (vs Local WP, DDEV, Lando, wp-env, XAMPP)

Built after auditing 7 competitor tools. The gaps matrix closes on day one:

Need matrix Local/Studio DDEV/Lando wp-env
Multi-site in seconds ✅ one command ✅ GUI ✅ ⚠️ single-site
Works on Podman ✅ first-class ❌ ⚠️ ❌
Zero-daemon offline tests ✅ 365 stub asserts ❌ ❌ ❌
Per-site WP core version pinning ✅ ⚠️ ⚠️ ⚠️
One-command public tunnel ✅ ✅ paid ⚠️ ❌
Portable tar.gz bundle w/ manifest ✅ ⚠️ ❌ ❌
No router container, no root daemon ✅ ❌ ❌ ❌
JSON CLI for automation ✅ every cmd ❌ ⚠️ ⚠️

Full analysis: docs/competitor-analysis.html

📖 Command Reference

Lifecycle 
./matrix start [site]      # no arg: core services · with arg: that site
./matrix stop  [site]      # no arg: everything · with arg: that site
./matrix restart [site]
./matrix status            # overview table
./matrix list              # all sites; --json for machine-readable
./matrix clean             # prune unused containers/images/volumes
Create & configure 
./matrix create shop                                # WordPress, PHP 8.3 default
./matrix create legacy --php-version=7.4            # side-by-side PHP
./matrix create lab    --wp-version=6.4             # pin WP core (6.4|6.5|6.6|latest)
./matrix create team   --multisite=subdomain        # network at creation
./matrix create shop   --preset=woocommerce         # presets from config/presets/
./matrix preset                                     # list available presets
./matrix edit site --memory=512M --cpu=1            # per-site resource limits
./matrix clone src dst · ./matrix reset name · ./matrix remove name

Other stacks — --type= picks the runtime, webroot and provisioning. PHP floors are enforced at create.

./matrix create shop     --type=laravel            # PHP ≥ 8.2 · public/ · composer create-project
./matrix create api      --type=symfony            # PHP ≥ 8.2 · public/
./matrix create cms      --type=drupal             # PHP ≥ 8.3 · web/ · settings.php pre-seeded
./matrix create intranet --type=joomla             # PHP ≥ 8.1 · Joomla 5 · wizard creds printed at create
./matrix create docs     --type=grav               # PHP ≥ 8.1 · no database at all

--wp-version, --multisite, --preset and stack=apache are WordPress-only. wp-cli, check and optimize refuse non-wp sites; clone/reset/export/import adapt per type.

TLS, domains, tunnels 
./matrix ssl mysite [--force] [--revoke] [--json]   # HTTPS on :9201 (port+1000)
./matrix domain mysite mysite.test [--yes]          # /etc/hosts entry, sudo-gated
./matrix share mysite --yes                         # cloudflared → ngrok → bore
Portability & ops 
./matrix export mysite --out bundle.tar.gz          # manifest + files + sha'd dump
./matrix import bundle.tar.gz newsite [--yes]
./matrix backup mysite --schedule=daily --retention=7
./matrix cron-install mysite · ./matrix cron-remove mysite
WP core & quality 
./matrix wp mysite plugin install query-monitor --activate
./matrix check [site] [path]                        # phpcs + phpstan level 9
./matrix test lab --wp-versions=6.4,6.5 [--json]    # compat matrix rows
./matrix rest mysite                                # REST API metadata
Introspection 
./matrix doctor [--json]                            # bootstrap checks
./matrix info mysite [--json]
./matrix url mysite
./matrix logs [site|db|redis|phpmyadmin]
./matrix shell wp|db|nginx [site]
scripts/health-check.sh                             # runtime deep-check

🏗️ Architecture

┌────────────────────────────── host ──────────────────────────────┐
│                                                                  │
│   matrix (bash) ◄── one entry point; validates, mutates, logs    │
│      │                                                           │
│      ├── generated state: docker-compose.yml · config/nginx/*    │
│      ├── ssl-certs/<site>/ · .cron/<site>.cron · backups/        │
│      └── frontend (Node/Express :8500) ── shells out to matrix   │
│                                                                  │
└──────────────────────────────┬───────────────────────────────────┘
                               ▼  $CONTAINER_RUNTIME / $DOCKER_COMPOSE
┌────────────────────────── containers ────────────────────────────┐
│  wp_<site> (wordpress:phpX.X-fpm | matrix-php:X.X) ⇄ nginx_<site>  │
│                    webroot: / · public/ (laravel,symfony) · web/   │
│                            (drupal) — grav has no database         │
│  wp_db (MySQL :3306) · redis · phpmyadmin (:8200)                │
│  wp-cli → ephemeral wordpress:cli, joins the live db network     │
└──────────────────────────────────────────────────────────────────┘

Note

Generated files are not source. docker-compose.yml entries, nginx confs, and certs are produced by matrix — ./matrix repair regenerates them at any time.

🧪 Testing & TDD

Strict red → green → refactor per phase. Failing tests are committed before the implementation.

Methodology: docs/TDD-IMPLEMENTATION.md

Suite Asserts What it pins
site-types-test.sh 169 6-stack registry, provisioning, compose/nginx/repair type-awareness
site-state-test.sh 34 Compose + live-container state seam
stubs-test.sh 4 docker/compose stub infrastructure
ssl-test.sh 12 cert generation, port math, domains
multisite-test.sh 20 multisite-at-creation contract
presets-test.sh 17 golden-parity preset loader
doctor-test.sh 18 every check + exit codes
export-import-test.sh 33 bundle round-trip, sha, name rules
wp-version-test.sh 21 pinning + compat matrix
share-test.sh 16 provider detection, url extraction, cleanup
ops-test.sh 21 schedules, crontab blocks, auth middleware

All stub suites run offline — no Docker daemon needed. Plus 62 Jest tests for the dashboard API.

# the release bar — run before every commit
bash -n matrix && bash -n scripts/*.sh
for t in tests/bash/*-test.sh; do bash "$t"; done
npm --prefix frontend test
./matrix info <site> --json | python3 -m json.tool

🗺️ Roadmap

  • Phase 0 — offline stub test infrastructure
  • Phase 1 — auto-HTTPS + optional domains
  • Phase 2 — multisite at creation
  • Phase 3 — presets as files
  • Phase 4 — matrix share tunnels
  • Phase 5 — matrix doctor
  • Phase 6 — export/import bundles
  • Phase 7 — WP version pinning + compat lab
  • Phase 8 — scheduled backups + dashboard token auth
  • Multi-stack — --type=laravel|symfony|drupal|joomla|grav alongside wp
  • Push/pull hosting sync (WP Engine/Kinsta-style)
  • Apache-stack TLS parity
  • Blueprint marketplace

🤝 Contributing

git checkout -b feat/my-feature
# 1. failing test first  →  tests/bash/feat-test.sh
# 2. implementation      →  keep the release bar green
# 3. docs in same commit →  README.md + AGENTS.md

Dev guide: AGENTS.md

📜 License

MIT License — see LICENSE for details.