> ## Documentation Index
> Fetch the complete documentation index at: https://zepeed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Using Docker Compose

Install and run Zepeed using Docker Compose.

## Requirements

Install the following on your system:

<Tabs>
  <Tab title="macOS">
    * **Docker Desktop**: [Download](https://www.docker.com/products/docker-desktop)
  </Tab>

  <Tab title="Linux">
    * **Docker Engine**: [Installation guide](https://docs.docker.com/engine/install/)
    * **Docker Compose**: Included with Docker Engine 24.0+
  </Tab>

  <Tab title="Windows">
    * **Docker Desktop**: [Download](https://www.docker.com/products/docker-desktop)
  </Tab>
</Tabs>

Verify installation:

```bash theme={null}
docker --version
docker compose version
```

## Setup

<Steps>
  <Step title="Clone repository">
    Clone the Zepeed repository to your local machine.

    ```bash theme={null}
    git clone https://github.com/MarJose123/zepeed.git
    cd zepeed
    ```
  </Step>

  <Step title="Create environment configuration">
    Copy the example environment file for your target environment. For development:

    ```bash theme={null}
    cp .env.dev.example .env
    ```

    For production:

    ```bash theme={null}
    cp .env.prod.example .env
    ```

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

  <Step title="Configure environment variables">
    Edit the `.env` file to match your deployment requirements. At minimum, set:

    ```env theme={null}
    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
    ```

    <Warning>
      In production, never commit `.env` to version control. Use secrets management tools (Kubernetes Secrets, Docker Secrets, HashiCorp Vault) instead.
    </Warning>
  </Step>

  <Step title="Start containers">
    Build and start all services in detached mode.

    ```bash theme={null}
    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
  </Step>

  <Step title="Initialize database">
    Run database migrations and seed initial data.

    ```bash theme={null}
    docker compose exec app php artisan migrate
    docker compose exec app php artisan db:seed
    ```

    <Note>
      If migrations fail with "No such table" errors, ensure the MySQL container is healthy before retrying. Check with `docker compose ps`.
    </Note>
  </Step>

  <Step title="Generate application key">
    If you haven't set `APP_KEY` in your `.env` file, generate it now.

    ```bash theme={null}
    docker compose exec app php artisan key:generate
    ```

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

    ```bash theme={null}
    docker compose restart app
    ```
  </Step>

  <Step title="Create a user account">
    Open the Docker terminal for the `app` container and run the following command to create your initial user account:

    ```bash theme={null}
    docker compose exec app php artisan app:create-user-account
    ```

    Follow the interactive prompts to set the user details.
  </Step>

  <Step title="Verify installation">
    Open your browser and navigate to the application URL:

    ```text theme={null}
    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:

    ```bash theme={null}
    docker compose ps
    ```

    Expected output shows all containers with status "Up".
  </Step>
</Steps>

## Essential commands

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
docker compose ps mysql
docker compose exec mysql mysql -u root -p -e "SELECT 1"
```

If MySQL fails to start, check data directory permissions:

```bash theme={null}
docker compose exec mysql chmod 755 /var/lib/mysql
```

### Application errors after startup

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

```bash theme={null}
docker compose logs mysql | grep "Ready for connections"
```

Then verify the app is running:

```bash theme={null}
docker compose restart app
docker compose logs app
```

### Reset to clean state

```bash theme={null}
docker compose down -v
docker compose up -d
docker compose exec app php artisan migrate
docker compose exec app php artisan db:seed
```