Docker Development

Laravel Sail provides a Docker-powered local development environment for TorrentPier. This guide covers everything you need to know about using Sail for development.

Prerequisites

Before getting started with Sail, ensure you have:

Docker Desktop installed and running
Git for cloning the repository
A terminal/command line interface

tip

For Windows users, we recommend using WSL2 (Windows Subsystem for Linux) for the best experience.

Quick Start

1. Clone the Repository

git clone https://github.com/torrentpier/torrentpier.git
cd torrentpier

2. Copy Environment File

cp .env.sail.example .env

3. Install Dependencies

If you don't have PHP installed locally, you can use a temporary container:

docker run --rm \
    -u "$(id -u):$(id -g)" \
    -v "$(pwd):/var/www/html" \
    -w /var/www/html \
    laravelsail/php84-composer:latest \
    composer install --ignore-platform-reqs

4. Start Sail

./vendor/bin/sail up -d

5. Generate Application Key

./vendor/bin/sail artisan key:generate

6. Run Migrations

./vendor/bin/sail artisan migrate

7. Install Frontend Dependencies

./vendor/bin/sail npm install
./vendor/bin/sail npm run dev

Your application will be available at:

Application: http://localhost
Mailpit (Email testing): http://localhost:8025
Meilisearch: http://localhost:7700

Sail Configuration

Environment Variables

The .env.sail.example file contains pre-configured settings for Docker services:

# Database
DB_CONNECTION=pgsql
DB_HOST=pgsql
DB_PORT=5432
DB_DATABASE=torrentpier
DB_USERNAME=sail
DB_PASSWORD=password

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# Meilisearch
MEILISEARCH_HOST=http://meilisearch:7700
MEILISEARCH_KEY=masterKey

# Mailpit
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025

# MinIO
AWS_ACCESS_KEY_ID=sail
AWS_SECRET_ACCESS_KEY=password
AWS_BUCKET=local
AWS_ENDPOINT=http://minio:9000
AWS_USE_PATH_STYLE_ENDPOINT=true

Services

TorrentPier's Sail configuration includes:

PostgreSQL 17 - Primary database
Redis - Caching and queues
Meilisearch - Full-text search engine
Mailpit - Email testing interface
MinIO - S3-compatible object storage for file uploads

Customizing Services

To add additional services:

./vendor/bin/sail artisan sail:add

Available services include:

MySQL
MariaDB
MongoDB
Valkey
Memcached
Typesense
RabbitMQ
Selenium
Soketi

Common Commands

Starting and Stopping

# Start all services
./vendor/bin/sail up -d

# Stop all services
./vendor/bin/sail stop

# Stop and remove containers
./vendor/bin/sail down

# Remove containers and volumes (full reset)
./vendor/bin/sail down -v

Artisan Commands

# Run any Artisan command
./vendor/bin/sail artisan [command]

# Examples:
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan db:seed
./vendor/bin/sail artisan queue:work
./vendor/bin/sail artisan scout:import

Composer Commands

# Install dependencies
./vendor/bin/sail composer install

# Update dependencies
./vendor/bin/sail composer update

# Add a package
./vendor/bin/sail composer require package/name

NPM Commands

# Install dependencies
./vendor/bin/sail npm install

# Run development server
./vendor/bin/sail npm run dev

# Build for production
./vendor/bin/sail npm run build

Testing

# Run all tests
./vendor/bin/sail test

# Run specific test
./vendor/bin/sail test tests/Feature/ExampleTest.php

# Run tests with coverage
./vendor/bin/sail test --coverage

Database Operations

# Access PostgreSQL CLI
./vendor/bin/sail psql

# Export database
./vendor/bin/sail exec pgsql pg_dump -U sail torrentpier > backup.sql

# Import database
./vendor/bin/sail exec pgsql psql -U sail torrentpier < backup.sql

Shell Access

# Access application container
./vendor/bin/sail shell

# Access as root
./vendor/bin/sail root-shell

# Access specific service
./vendor/bin/sail exec redis redis-cli

Shell Alias

For convenience, add this alias to your shell configuration:

# ~/.bashrc or ~/.zshrc
alias sail='sh $([ -f sail ] && echo sail || echo vendor/bin/sail)'

Now you can use:

sail up
sail artisan migrate
sail npm run dev

Debugging with Xdebug

Enable Xdebug

Set in your .env file:

SAIL_XDEBUG_MODE=debug,develop

Configure Your IDE

PHPStorm

Go to Settings → PHP → Servers
Add a new server:
- Name: localhost
- Host: localhost
- Port: 80
- Debugger: Xdebug
- Use path mappings: Yes
- Project files: /var/www/html

VS Code

Install the PHP Debug extension and add to .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Listen for Sail Xdebug",
            "type": "php",
            "request": "launch",
            "port": 9003,
            "pathMappings": {
                "/var/www/html": "${workspaceFolder}"
            }
        }
    ]
}

Performance Optimization

Windows (WSL2)

For better performance on Windows:

Clone the project inside WSL2:

cd ~/projects
git clone https://github.com/torrentpier/torrentpier.git

Configure Vite for HMR:

   // vite.config.js
   export default defineConfig({
       server: {
           hmr: {
               host: 'localhost',
           },
       },
   });

macOS

Enable VirtioFS in Docker Desktop:

Go to Docker Desktop → Settings → General
Enable "Use Virtualization framework"
Go to Settings → Resources → File sharing
Enable "VirtioFS"

Production Builds

Building for Production

# Build production Docker image
docker build -f Dockerfile.production -t torrentpier:latest .

# Using docker-compose
docker compose -f docker-compose.production.yml build

Running Production Containers

# Start production stack
docker compose -f docker-compose.production.yml up -d

# View logs
docker compose -f docker-compose.production.yml logs -f

# Stop production stack
docker compose -f docker-compose.production.yml down

Troubleshooting

Port Conflicts

If you get port conflicts, customize ports in .env:

APP_PORT=8080
FORWARD_DB_PORT=5433
FORWARD_REDIS_PORT=6380
FORWARD_MEILISEARCH_PORT=7701
FORWARD_MAILPIT_PORT=1026
FORWARD_MAILPIT_DASHBOARD_PORT=8026

Permission Issues

Fix permission issues:

# Set correct ownership
./vendor/bin/sail exec laravel.test chown -R sail:sail storage bootstrap/cache

# Or from host
sudo chown -R $(id -u):$(id -g) storage bootstrap/cache

Container Won't Start

Check logs:

./vendor/bin/sail logs laravel.test

Rebuild containers:

./vendor/bin/sail build --no-cache
./vendor/bin/sail up -d

Reset everything:

./vendor/bin/sail down -v
rm -rf vendor node_modules
# Then start from Quick Start

Database Connection Issues

If you can't connect to the database:

Wait for PostgreSQL to be ready:

./vendor/bin/sail exec pgsql pg_isready -h localhost -U sail

Check PostgreSQL logs:

./vendor/bin/sail logs pgsql

Verify credentials match .env file

Advanced Usage

Custom PHP Extensions

To add PHP extensions, first publish Sail's Dockerfiles:

./vendor/bin/sail artisan sail:publish

Then modify docker/8.4/Dockerfile:

RUN apt-get update && apt-get install -y \
    php8.4-gmp \
    php8.4-imagick

Finally rebuild:

./vendor/bin/sail build --no-cache

Running Multiple Projects

Use different APP_PORT values:

# Project 1 (.env)
APP_PORT=8001

# Project 2 (.env)
APP_PORT=8002

Using Different PHP Versions

Publish Sail's Dockerfiles:

./vendor/bin/sail artisan sail:publish

Modify docker-compose.yml:

services:
    laravel.test:
        build:
           context: ./docker/8.3

Rebuild:

./vendor/bin/sail build --no-cache

GitHub Codespaces / Devcontainers

For GitHub Codespaces support:

./vendor/bin/sail artisan sail:install --devcontainer

This creates .devcontainer/devcontainer.json for use with:

GitHub Codespaces
VS Code Remote Containers
JetBrains Gateway

Additional Resources

Getting Help

If you encounter issues:

Check the troubleshooting section
Search existing GitHub Issues
Ask on our support forum
Create a new issue with:
- Your OS and Docker version
- Steps to reproduce
- Error messages/logs

Prerequisites​

Quick Start​

1. Clone the Repository​

2. Copy Environment File​

3. Install Dependencies​

4. Start Sail​

5. Generate Application Key​

6. Run Migrations​

7. Install Frontend Dependencies​

Sail Configuration​

Environment Variables​

Services​

Customizing Services​

Common Commands​

Starting and Stopping​

Artisan Commands​

Composer Commands​

NPM Commands​

Testing​

Database Operations​

Shell Access​

Shell Alias​

Debugging with Xdebug​

Enable Xdebug​

Configure Your IDE​

PHPStorm​

VS Code​

Performance Optimization​

Windows (WSL2)​

macOS​

Production Builds​

Building for Production​

Running Production Containers​

Troubleshooting​

Port Conflicts​

Permission Issues​

Container Won't Start​

Database Connection Issues​

Advanced Usage​

Custom PHP Extensions​

Running Multiple Projects​

Using Different PHP Versions​

GitHub Codespaces / Devcontainers​

Additional Resources​

Getting Help​