Configuration

After Installation puts the code on disk and composer install brings the dependencies, configuration is where the application is wired to your environment — your database, your Redis, your URL, your queue worker.

System requirements

• PHP 8.1 or higher
• Laravel 10.0 or higher
• MySQL or compatible (the default DB_CONNECTION)
• Redis server running locally — used for cache, sessions, and queues
• Node.js + npm for the front-end assets

Environment file

Copy .env.example to .env in the project root, then generate an application key:

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

The key signs cookies and encrypted values. Without it the application refuses to boot.

Database

Create a new database (the default name is winch) and update the credentials in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=winch
DB_USERNAME=root
DB_PASSWORD=

Then run migrations:

php artisan migrate

For a clean slate with seed data (use only on a local database — it drops every table first):

php artisan migrate:fresh --seed

Application URL

Set APP_URL to whatever your local web server serves:

APP_URL=http://winch.test

This is used by mailables, signed URLs, queue dashboards, and anything else that builds an absolute URL outside of a request.

Redis

Make sure Redis is running locally and update the connection details in .env:

REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

The project uses Redis for cache, session storage, and the queue driver. If Redis isn't running, the application boots but breaks the moment anything cache- or session-related runs.

Front-end assets

npm install

For local development with hot reload run npm run dev; for a production build run npm run build.

Git hooks

Install the project's pre-push and commit-msg hooks:

./install-git-hooks.sh

The pre-push hook runs Pint, the translation-key checker, and a few other guards before letting a push leave your machine. Skipping it means CI catches what the hook would have caught — slower and noisier.

Queue worker

Anything that uses ShouldQueue requires a running worker. In a separate terminal:

php artisan queue:work

In production this is supervised; locally you start it manually when you need it.

Common cache and route commands

When config or routes don't seem to update, clear the caches:

php artisan optimize:clear
# or, individually:
php artisan config:clear
php artisan route:clear
php artisan view:clear

For production-style local testing, cache them:

php artisan config:cache
php artisan route:cache
php artisan view:cache

What to read next

Your environment boots — now get oriented and ship something:

• Your first PR — the natural next step: a complete change end-to-end, every file the pattern touches.
• Directory structure — where everything lives, so you can find the file a ticket points you at.
• Key concepts: DDD basics — how the codebase splits business logic from HTTP, and the patterns every change follows.