Using Docker Compose

Install and run Zepeed using Docker Compose.

Requirements

Install the following on your system:

macOS

• Docker Desktop: Download

Linux

• Docker Engine: Installation guide
• Docker Compose: Included with Docker Engine 24.0+

Windows

• Docker Desktop: Download

Verify installation:

docker --version
docker compose version

Setup

1. Clone repository

   Clone the Zepeed repository to your local machine.

   git clone https://github.com/MarJose123/zepeed.git
   cd zepeed
   
2. Create environment configuration

   Copy the example environment file for your target environment. For development:

   cp .env.dev.example .env
   

   For production:

   cp .env.prod.example .env
   

   The environment file contains configuration for the application, database, cache, mail, and external services.

3. Configure environment variables

   Edit the .env file to match your deployment requirements. At minimum, set:

   APP_NAME="Zepeed"
   APP_KEY=base64:YOUR_APP_KEY
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=http://localhost:8080
   APP_TIMEZONE=Asia/Manila
   
   PUSHER_APP_ID=
   PUSHER_APP_KEY=
   PUSHER_APP_SECRET=
   PUSHER_APP_CLUSTER=mt1
   PUSHER_HOST=soketi
   PUSHER_SCHEME=http
   PUSHER_PORT=6001
   
   VITE_APP_NAME="${APP_NAME}"
   VITE_PUSHER_APP_KEY="${PUSHER_APP_KEY}"
   VITE_PUSHER_APP_CLUSTER="${PUSHER_APP_CLUSTER}"
   VITE_PUSHER_HOST=localhost
   VITE_PUSHER_PORT="${PUSHER_PORT}"
   VITE_PUSHER_SCHEME="${PUSHER_SCHEME}"
   
   AUTORUN_LARAVEL_CONFIG_CACHE=false
   AUTORUN_LARAVEL_EVENT_CACHE=false
   AUTORUN_LARAVEL_OPTIMIZE=false
   AUTORUN_LARAVEL_ROUTE_CACHE=false
   AUTORUN_LARAVEL_VIEW_CACHE=false
   AUTORUN_LARAVEL_MIGRATION_SEED=true
   

   In production, never commit .env to version control. Use secrets management tools (Kubernetes Secrets, Docker Secrets, HashiCorp Vault) instead.

4. Start containers

   Build and start all services in detached mode.

   docker compose up -d
   

   Docker Compose will:

   1. Build the Zepeed application image
   2. Pull MySQL, Redis, and Mailpit images
   3. Create containers and networks
   4. Start all services
5. Initialize database

   Run database migrations and seed initial data.

   docker compose exec app php artisan migrate
   docker compose exec app php artisan db:seed
   

   If migrations fail with “No such table” errors, ensure the MySQL container is healthy before retrying. Check with docker compose ps.

6. Generate application key

   If you haven’t set APP_KEY in your .env file, generate it now.

   docker compose exec app php artisan key:generate
   

   Update your .env file with the generated key and restart the application:

   docker compose restart app
   
7. Create a user account

   Open the Docker terminal for the app container and run the following command to create your initial user account:

   docker compose exec app php artisan app:create-user-account
   

   Follow the interactive prompts to set the user details.

8. Verify installation

   Open your browser and navigate to the application URL:

   http://localhost
   

   You should see the Zepeed login page. Log in with default credentials (if seeded) or create a new account via the application interface.

   Verify services are running:

   docker compose ps
   

   Expected output shows all containers with status “Up”.

Essential commands

# View logs
docker compose logs -f app

# Run artisan commands
docker compose exec app php artisan <command>

# Stop containers
docker compose stop

# Rebuild after Dockerfile changes
docker compose up -d --build app

Troubleshooting

Container fails to start

Check logs for error messages:

docker compose logs app
docker compose logs mysql

Common issues:

• Port already in use: Change port mapping in compose.yaml
• Insufficient disk space: Clean up with docker system prune
• Permission denied: Ensure Docker daemon is running and you have permissions

Database connection fails

Verify MySQL is running and healthy:

docker compose ps mysql
docker compose exec mysql mysql -u root -p -e "SELECT 1"

If MySQL fails to start, check data directory permissions:

docker compose exec mysql chmod 755 /var/lib/mysql

Application errors after startup

Wait for MySQL to finish initialization. The first startup takes longer:

docker compose logs mysql | grep "Ready for connections"

Then verify the app is running:

docker compose restart app
docker compose logs app

Reset to clean state

docker compose down -v
docker compose up -d
docker compose exec app php artisan migrate
docker compose exec app php artisan db:seed