Local Development

Run Zepeed locally for development without Docker.

This guide is for contributors who want to run Zepeed from source on their own machine. If you just want to deploy Zepeed, use Using Docker Compose instead.

Requirements

• PHP 8.4+
• Composer
• Bun (for the Vue/Vite frontend)
• Docker Desktop or OrbStack (for the database and supporting services)
• Git

Clone and install

1. Clone the repository

   git clone https://github.com/marjose123/zepeed.git
   cd zepeed
   
2. Install PHP dependencies

   composer install
   
3. Install frontend dependencies

   bun install
   
4. Configure environment

   cp .env.example .env
   php artisan key:generate
   

   Adjust database, mail, and provider settings in .env. See Environment Variables for the full reference.

5. Run database migrations

   php artisan migrate
   
6. Start dev servers

   Run the Laravel app and Vite dev server in parallel:

   php artisan serve
   bun run dev
   

   Then open http://localhost:8000.

Useful Composer scripts

Zepeed ships with helper scripts that combine formatters, linters, and tests.

Command	What it does
composer run format	Run Pint (PHP), Prettier, and ESLint fixes.
composer run analyse	Run PHPStan static analysis.
composer run rector	Apply Rector refactorings.
composer run test	Run the PHPUnit test suite.

Run all four before opening a pull request.

Tech stack

• Backend — Laravel 13, Fortify, Inertia.js (Laravel adapter)
• Frontend — Vue 3, shadcn/vue (reka-ui), Tailwind CSS v4
• Tooling — Vite, TypeScript, ESLint, Prettier, Pint, PHPStan, Rector
• Extras — Mailpit, Soketi/Reverb-ready scripts

Speedtest provider CLIs

Zepeed shells out to the official provider CLIs. When running locally outside Docker you may need to install them yourself:

• ookla/speedtest-cli
• librespeed/speedtest-cli
• mikkelam/fast-cli
• kavehtehrani/cloudflare-speed-cli

The Docker image bundles all four — prefer Docker if you do not want to manage these manually.

Tests and CI

The repository runs three GitHub Actions workflows on every push:

• API tests — PHPUnit suite against the HTTP API.
• PHPStan — Static analysis.
• Code style — Pint, Prettier, ESLint.

All three must pass before a PR can be merged. Run composer run format, composer run analyse, and composer run test locally to catch issues early.

Related pages

• Contribute
• Using Docker Compose
• Environment Variables