# Laravel Seraph Deployment Guide

## Overview
This guide covers deployment for both development and production environments, including Docker permission fixes for the `ca` user and `www-data` container user.

## Problem Solved
- **Host user `ca`** couldn't access files owned by `www-data`
- **Git operations** were failing due to permission denied errors
- **Docker container** couldn't write to storage directories
- **Public files** had incorrect permissions

## Quick Start

### 🚀 One-Command Production Deployment
```bash
sudo ./deploy-production.sh
```

### 🔧 Manual Production Deployment
```bash
# Step 1: Fix host permissions
sudo ./fix-host-permissions.sh

# Step 2: Deploy Docker
docker-compose -f docker-compose.production.yaml build
docker-compose -f docker-compose.production.yaml up -d

# Step 3: Verify
git status
docker-compose -f docker-compose.production.yaml ps
```

## Development Environment

### Prerequisites
- Docker and Docker Compose installed
- Git repository cloned
- User `ca` has access to the project directory

### Setup Development Environment
```bash
# Clone repository (if not already done)
git clone <repository-url>
cd seraph3

# Fix host permissions for development
sudo ./fix-host-permissions.sh

# Start development containers
docker-compose up -d

# Verify setup
git status
docker-compose ps
```

### Development Commands
```bash
# Run PHP commands in container
docker-compose exec app php artisan migrate
docker-compose exec app php artisan make:controller SomeController
docker-compose exec app php artisan tinker

# View logs
docker-compose logs app

# Access container shell
docker-compose exec app bash
```

## Production Environment

### Prerequisites
- Production server with Docker installed
- Domain configured for SSL
- Environment variables set up

### Production Deployment

#### Option 1: Automated Deployment
```bash
sudo ./deploy-production.sh
```

#### Option 2: Manual Deployment
```bash
# 1. Fix host permissions
sudo ./fix-host-permissions.sh

# 2. Verify Git works
git status
git pull

# 3. Build and deploy
docker-compose -f docker-compose.production.yaml build
docker-compose -f docker-compose.production.yaml up -d

# 4. Verify deployment
docker-compose -f docker-compose.production.yaml ps
```

### Production Commands
```bash
# Run PHP commands in production container
docker-compose -f docker-compose.production.yaml exec seraph_app php artisan migrate --force
docker-compose -f docker-compose.production.yaml exec seraph_app php artisan config:cache

# View production logs
docker-compose -f docker-compose.production.yaml logs seraph_app

# Access production container
docker-compose -f docker-compose.production.yaml exec seraph_app bash
```

## Permission System

### Shared Group Setup
The solution creates a shared group `seraph-app` that includes:
- **ca** (host user for development)
- **www-data** (Docker container user)

This allows both users to work with the same files without conflicts.

### Permission Structure

| Component | Owner | Group | Files | Directories | Purpose |
|-----------|-------|-------|-------|-------------|---------|
| **Host** | ca | seraph-app | 644 | 755 (setgid) | Development access |
| **Container** | www-data | seraph-app | 644 | 755 (setgid) | Production access |
| **Storage** | www-data | seraph-app | 644 | 775 | Laravel writable |
| **Public** | www-data | seraph-app | 644 | 755 | Web accessible |

### Security Features
- **644** for files: Owner read/write, group/others read
- **755** for directories: Owner read/write/execute, group/others read/execute
- **775** for writable directories: Owner/group read/write/execute
- **setgid bit**: New files inherit group ownership
- **Shared group**: Both users can access files safely

## Files and Scripts

### Core Scripts
- **`fix-host-permissions.sh`** - Fixes host permissions for `ca` user
- **`fix-permissions.sh`** - Fixes container permissions for `www-data` user
- **`deploy-production.sh`** - Complete production deployment script

### Docker Files
- **`dockerfile`** - Updated with shared group support
- **`docker-entrypoint.sh`** - Enhanced with permission handling
- **`docker-compose.production.yaml`** - Production Docker configuration

## Verification Commands

### Development Verification
```bash
# Check host permissions
ls -la
groups ca
groups www-data

# Test Git operations
git status
git pull

# Check development containers
docker-compose ps
```

### Production Verification
```bash
# Check container permissions
docker-compose -f docker-compose.production.yaml exec seraph_app ls -la /var/www/html

# Check container user
docker-compose -f docker-compose.production.yaml exec seraph_app whoami

# Check container groups
docker-compose -f docker-compose.production.yaml exec seraph_app groups

# Check container status
docker-compose -f docker-compose.production.yaml ps
```

## Troubleshooting

### Common Issues

#### Git Operations Fail
```bash
# Fix host permissions
sudo ./fix-host-permissions.sh

# Verify ownership
ls -la
groups ca
```

#### Docker Can't Write to Storage
```bash
# Fix container permissions
docker-compose -f docker-compose.production.yaml exec seraph_app ./fix-permissions.sh

# Or rebuild container
docker-compose -f docker-compose.production.yaml down
docker-compose -f docker-compose.production.yaml up -d
```

#### Containers Won't Start
```bash
# Check container logs
docker-compose -f docker-compose.production.yaml logs seraph_app

# Restart containers
docker-compose -f docker-compose.production.yaml down
docker-compose -f docker-compose.production.yaml up -d
```

#### Permission Denied Errors
```bash
# Manual host fix
sudo chown -R ca:seraph-app /home/ca/seraph3
sudo chmod -R g+w /home/ca/seraph3

# Manual container fix
docker-compose -f docker-compose.production.yaml exec seraph_app chown -R www-data:seraph-app /var/www/html
```

### Debug Commands
```bash
# Check current user and groups
whoami
groups

# Check file permissions
ls -la /home/ca/seraph3

# Check container user
docker-compose -f docker-compose.production.yaml exec seraph_app whoami

# Check container permissions
docker-compose -f docker-compose.production.yaml exec seraph_app ls -la /var/www/html
```

## Environment-Specific Configurations

### Development Environment
- **Services**: App, MySQL, Redis, Adminer
- **Ports**: 8000 (App), 3306 (MySQL), 6379 (Redis), 8080 (Adminer)
- **Volumes**: Local development files mounted
- **User**: ca (host) + www-data (container)

### Production Environment
- **Services**: App, MySQL, Redis, Nginx, Certbot
- **Ports**: 80 (HTTP), 443 (HTTPS), 3306 (MySQL), 6379 (Redis)
- **SSL**: Automatic Let's Encrypt certificates
- **User**: www-data (container) + ca (host for Git)

## Maintenance

### Regular Tasks
```bash
# Update code
git pull

# Rebuild containers (if needed)
docker-compose -f docker-compose.production.yaml build

# Restart services
docker-compose -f docker-compose.production.yaml restart

# Clear Laravel caches
docker-compose -f docker-compose.production.yaml exec seraph_app php artisan cache:clear
```

### Backup and Recovery
```bash
# Backup database
docker-compose -f docker-compose.production.yaml exec mysql mysqldump -u root -p database_name > backup.sql

# Restore database
docker-compose -f docker-compose.production.yaml exec -T mysql mysql -u root -p database_name < backup.sql
```

## Support

For issues not covered in this guide:
1. Check container logs: `docker-compose -f docker-compose.production.yaml logs seraph_app`
2. Verify permissions: `ls -la` and `docker-compose -f docker-compose.production.yaml exec seraph_app ls -la /var/www/html`
3. Test Git operations: `git status` and `git pull`
4. Check user groups: `groups ca` and `groups www-data`

## Quick Reference

### Development
```bash
# Start development
docker-compose up -d

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

# View logs
docker-compose logs app
```

### Production
```bash
# Deploy production
sudo ./deploy-production.sh

# Run artisan commands
docker-compose -f docker-compose.production.yaml exec seraph_app php artisan <command>

# View logs
docker-compose -f docker-compose.production.yaml logs seraph_app
```

### Permissions
```bash
# Fix host permissions
sudo ./fix-host-permissions.sh

# Fix container permissions
docker-compose -f docker-compose.production.yaml exec seraph_app ./fix-permissions.sh
``` 