Skip to main content

Contributor onboarding: run and test YAFFA locally

Thank you for your interest in contributing to YAFFA. This guide helps you set up a local development environment, run YAFFA, and validate your changes before opening a pull request.

This guide is for the YAFFA application repository at https://github.com/kantorge/yaffa.

Who this guide is for​

  • Developers contributing code, tests, translations, or assets to YAFFA
  • QA contributors who want to run smoke tests and automated tests locally

If you only want to run a personal YAFFA instance, see the installation guides, e.g. Install YAFFA using Docker for Windows.

Possible local development setups​

This guide covers three common local development setups for contributors:

  • Windows 11 + WSL2 + Docker Desktop
  • macOS (Intel or Apple Silicon) + Docker Desktop
  • Linux (Ubuntu, Debian, Fedora, etc.) + Docker Engine + Compose plugin

Native Windows without WSL2 is possible, but it is not recommended for day-to-day contributor work.

Prerequisites​

Install the following tools before continuing:

  • Git
  • Docker with Compose support (Docker Desktop or Docker Engine + Compose plugin)
  • PHP 8.4+
  • Composer 2.x
  • Node.js 20+ and npm

Verify your installation in your terminal:

git --version
docker --version
docker compose version
php -v
composer --version
node -v
npm -v

If one of these commands fails, install or fix that tool first.

Before you begin​

Use these rules throughout this guide:

  • Run host commands directly in your terminal.
  • Run containerized app commands through Sail (./vendor/bin/sail ...).
  • Keep the repository in a performant local filesystem.
    • On Windows, keep it inside your WSL home directory, not under /mnt/c.

Follow these steps in order from a clean machine.

1. Clone the YAFFA application repository​

git clone https://github.com/kantorge/yaffa.git
cd yaffa

2. Prepare the environment file​

cp .env.example .env

Generate an application key:

php artisan key:generate

3. Install dependencies (host machine)​

composer install
npm ci

4. Start the local stack​

Make sure Docker is running, then start the app and required services:

./vendor/bin/sail up -d

This starts the app and required services defined by YAFFA's local Docker setup. For the first time, it may take a few minutes to pull images and build containers.

Check service status:

./vendor/bin/sail ps

5. Initialize the app​

./vendor/bin/sail artisan migrate

For first-time contributor setup, also prepare frontend and cache state:

6. Build or run frontend assets​

Build assets for the first time, or start the dev server for active development.

For one-time build:

npm run build

For active frontend development:

npm run dev

7. Open the app​

Open http://localhost (or your configured APP_URL) and verify the YAFFA login screen appears.

If your app is not on port 80, check your exposed port in the running containers and open that URL.

Local testing workflow for contributors​

Run these checks before opening a pull request.

1. Baseline backend tests (required)​

./vendor/bin/sail php ./vendor/bin/phpunit --testsuite Unit,Feature

2. Build frontend assets (required)​

npm run build

3. Dusk browser tests (required for UI-sensitive changes)​

YAFFA also runs Dusk browser tests in CI. If your change affects UI flows, run Dusk locally as well:

./vendor/bin/sail artisan dusk

OS-specific guidance​

Windows 11 + WSL2​

  • Install Docker Desktop and enable WSL integration for your Linux distribution.
  • Open your WSL terminal and work from your Linux home directory.
  • Do not run this flow from Windows Command Prompt against files in /mnt/c.
  • If Docker commands fail in WSL, restart Docker Desktop and re-open the WSL terminal.

macOS​

  • Docker Desktop is the simplest setup for contributor parity.
  • Apple Silicon contributors may see slower first-time image builds when multi-arch images are pulled.
  • If containers are slow to start, increase Docker Desktop CPU and memory allocation.

Linux​

  • Install Docker Engine and Compose plugin from your distro or Docker docs.
  • Add your user to the docker group to avoid repeated sudo usage.
  • After adding your user to docker group, log out and log in again.

Troubleshooting​

./vendor/bin/sail not found​

Run composer install first. Sail is installed in vendor/bin as part of dependencies.

Database connection errors during migrate​

  • Confirm containers are running with ./vendor/bin/sail ps
  • Retry after a short wait: the database service can need extra startup time
  • Re-run migration command: ./vendor/bin/sail artisan migrate

Frontend build errors​

  • Ensure Node.js and npm versions are installed correctly
  • Reinstall frontend dependencies with npm ci
  • Re-run npm run build

Port already in use​

  • Stop conflicting local services or adjust your Docker port mapping
  • Restart stack with ./vendor/bin/sail down then ./vendor/bin/sail up -d