crew_admin/readme.md

# Crew Admin Panel

A comprehensive administration platform built with Laravel 5.2 for managing custom sportswear operations, product catalogs, and customer relationships.

## Overview

Crew Admin is a web-based administration interface designed to streamline business operations for Crew Sportswear's custom merchandise management. The platform provides robust tools for inventory control, order processing, and analytics.

## Technology Stack

- **Framework**: Laravel 5.2
- **PHP Version**: 7.4
- **Web Server**: Apache 2.4
- **Database**: MySQL (separate container)
- **Reverse Proxy**: Traefik with Let's Encrypt SSL
- **Containerization**: Docker & Docker Compose
- **CI/CD**: Gitea Actions

## Features

- User authentication and role-based access control
- Product and inventory management
- Order processing and tracking
- Customer relationship management
- Analytics and reporting dashboard
- RESTful API endpoints
- Secure HTTPS communication
- Automated deployment workflows

## Requirements

- Docker Engine 20.10+
- Docker Compose 2.0+
- PHP 7.4 (for local development)
- Composer 1.x
- MySQL 5.7+ or MariaDB 10.3+

## Deployment

### Production Deployment

Production is automatically deployed via Gitea Actions when pushing to `main` or `master` branch.

**Production URL**: https://admin.crewsportswear.app

```bash
# Trigger production deployment
git push origin main
```

The deployment workflow:
1. Builds Docker image
2. Transfers image to production server via SSH
3. Deploys to `/var/www/apps/crew_admin`
4. Runs migrations and cache clearing
5. Performs health check

### Development Deployment

Development environment is automatically deployed when pushing to `dev` branch.

**Development URL**: https://dev-admin.crewsportswear.app

```bash
# Trigger dev deployment
git push origin dev
```

### Manual Deployment

```bash
# Build and deploy production
docker compose -f docker-compose.prod.yml up -d --build

# Build and deploy development
docker compose -f docker-compose.dev.yml up -d --build
```

## Configuration

### Environment Variables

Create a `.env` file in the deployment directory with:

```env
# Application
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:your-32-character-key-here
APP_URL=https://admin.crewsportswear.app

# Database (external MySQL container)
DB_CONNECTION=mysql
DB_HOST=mysql_container_name
DB_PORT=3306
DB_DATABASE=crew_admin
DB_USERNAME=crew_admin_user
DB_PASSWORD=your-secure-password

# Additional configuration
IMAGES_DIRECTORY=/path/to/images
PRODUCTION_PRIVATE_SERVER=http://internal-server
```

### SSL/HTTPS Configuration

The application uses Traefik as a reverse proxy with automatic Let's Encrypt SSL certificates. The certresolver is set to `le` in `docker-compose.prod.yml`:

```yaml
traefik.http.routers.crew-admin.tls=true
traefik.http.routers.crew-admin.tls.certresolver=le
```

Ensure your DNS points to the server before deployment.

## Docker Networks

The application requires two Docker networks:

- `traefik-public`: External network for Traefik routing
- `crew-app-net`: Internal network for inter-service communication

These are automatically created by the deployment script.

## Local Development

```bash
# Install dependencies
composer install

# Copy environment file
cp .env.example .env

# Generate application key
php artisan key:generate

# Configure database in .env file
# Run migrations
php artisan migrate

# Start development server
php artisan serve
```

## Gitea Workflows

### Production Deployment Workflow
- **File**: `.gitea/workflows/deploy.yml`
- **Trigger**: Push to `main` or `master`
- **Target**: `/var/www/apps/crew_admin`
- **Domain**: admin.crewsportswear.app

### Development Deployment Workflow
- **File**: `.gitea/workflows/deploy-dev.yml`
- **Trigger**: Push to `dev`
- **Target**: `/var/www/apps/crew_admin_dev`
- **Domain**: dev-admin.crewsportswear.app

### Docker Registry Build Workflow
- **File**: `.gitea/workflows/build-push.yml`
- **Trigger**: Version tag (e.g., `v1.0.0`)
- **Action**: Builds and pushes to Docker registry

## Required Secrets

Configure these secrets in your Gitea repository settings:

- `DEPLOY_SSH_KEY`: SSH private key for deployment server
- `DEPLOY_HOST`: Deployment server hostname/IP
- `DEPLOY_USER`: SSH username for deployment

## Artisan Commands

Common commands for cache management:

```bash
# Clear all caches
docker exec crew_admin_app php artisan cache:clear
docker exec crew_admin_app php artisan config:clear
docker exec crew_admin_app php artisan view:clear

# Rebuild caches
docker exec crew_admin_app php artisan config:cache
docker exec crew_admin_app php artisan route:cache
```

## Troubleshooting

### Container Not Starting

```bash
# Check container logs
docker logs crew_admin_app

# Check if networks exist
docker network ls | grep -E "traefik-public|crew-app-net"

# Recreate networks if needed
docker network create traefik-public
docker network create crew-app-net
```

### SSL Certificate Issues

```bash
# Check Traefik logs
docker logs traefik 2>&1 | grep crew-admin

# Verify DNS is pointing correctly
dig admin.crewsportswear.app
```

### Database Connection Issues

```bash
# Verify database container is running
docker ps | grep mysql

# Check network connectivity
docker exec crew_admin_app ping mysql_container_name
```

## License

Proprietary software for Crew Sportswear operations.