This guide walks you through setting up the project on a local development machine. For production deployment, see the Deployment page.

ℹ️

Before you begin Make sure PHP 8.1+, Composer 2.x, and MySQL 5.7+ are installed on your machine.

Requirements

Dependency	Version	Notes
`PHP`	8.1+	Required by CI 4.4+
`MySQL`	5.7 / 8.0	Primary database
`Composer`	2.x	Dependency management
`Node.js`	18+ (optional)	Only needed for asset pipeline

Steps

Clone the repository

terminal bash

git clone https://github.com/your-org/myapp.git
cd myapp

Install PHP dependencies
```
composer install
```
Copy the environment file
```
cp env .env
```
Edit .env with your local database credentials and base URL.

Run migrations and seeders

php spark migrate
php spark db:seed MainSeeder

Start the dev server
```
php spark serve
```
App will be available at http://localhost:8080.

⚠️

Use 127.0.0.1, not localhost MySQL on some setups resolves localhost to a socket path instead of TCP. Use 127.0.0.1 in .env to avoid connection errors.

Configuration

Key variables to configure in .env:

Variable	Default	Description
CI_ENVIRONMENT required	`production`	Set to `development` locally to enable error display.
database.default.hostname required	—	MySQL hostname. Use `127.0.0.1`.
app.baseURL required	—	Full URL with trailing slash. e.g. `http://localhost:8080/`
JWT_SECRET optional	—	Only needed if JWT API auth is enabled.

🚫

Never commit .env The file is in .gitignore. Use your CI/CD secrets manager for production values.

Sample flowchart

Use Mermaid blocks when a setup, request path, or job pipeline is easier to explain visually. Any docs page can now render a diagram by adding a <div class="mermaid"> block like the example below.

Reusable in other docs pages Copy this section structure into any docs view and replace the diagram text with your own flow.

flowchart TD A[Clone repository] --> B[Install Composer dependencies] B --> C[Copy env to .env] C --> D[Update database and app settings] D --> E[Run migrations and seeders] E --> F[Start local server] F --> G[Open docs or app in browser]

<div class="mermaid">
flowchart TD
    A[Start] --> B[Process]
    B --> C[Done]
</div>