📦 Installation Guide

Step-by-step guide to get Dockavel running in production or locally.

---

Prerequisites

Server (Production):

• Ubuntu 20.04+ (24.04 recommended)
• 2GB RAM minimum (4GB recommended)
• Root or sudo access
• Domain name pointed to your server

Local (Development):

• Docker Desktop (Windows/Mac) or Docker Engine (Linux)
• Git

---

Quick Start (Production)

1. Initial Server Setup

Run once on a fresh Ubuntu server:

curl -fsSL https://raw.githubusercontent.com/mg2k4/Dockavel/main/scripts/server-setup.sh | sudo bash

This installs Docker, configures the firewall (UFW), sets up Fail2Ban, and creates a deploy user.

Duration: ~5 minutes

2. Deploy Application

# SSH as deploy user
ssh deploy@your-server-ip

# Clone and deploy
cd /var/www
git clone git@github.com:mg2k4/Dockavel.git app
cd app
./scripts/deploy.sh prod

The script will:

• Detect your environment (Cloudflare or direct)
• Build Docker containers
• Install dependencies
• Set up SSL with Let's Encrypt
• Run migrations
• Start services

Duration: ~3-5 minutes

3. Access Your App

https://your-domain.com

---

Local Development

git clone git@github.com:mg2k4/Dockavel.git
cd Dockavel
./scripts/deploy.sh dev

Access at:

• http://localhost — Main app
• https://localhost — HTTPS (self-signed cert)
• http://localhost:5173 — Vite HMR

---

SSL Configuration

Let's Encrypt (DNS-only or no Cloudflare)

Automatic! The deploy script handles everything.

Cloudflare (Proxied — Orange Cloud)

1. In Cloudflare Dashboard:
   • SSL/TLS → Full (Strict)
   • Create Origin Certificate (15 years)
2. Save certificates:

   # As deploy user
   mkdir -p data/certbot/conf/live/your-domain.com/
   nano data/certbot/conf/live/your-domain.com/fullchain.pem  # Paste origin cert
   nano data/certbot/conf/live/your-domain.com/privkey.pem    # Paste private key
   chmod 600 data/certbot/conf/live/your-domain.com/*.pem
   

3. Deploy:

   ./scripts/deploy.sh prod
   

---

Post-Installation

Update your application:

ssh deploy@your-server
cd /var/www/app
git pull origin main
./scripts/update.sh

View logs:

docker compose logs -f
docker compose logs -f app    # Just app container

Configure backups:

# Automate with cron
crontab -e
# Add: 0 2 * * * cd /var/www/app && ./scripts/backup.sh

See TROUBLESHOOTING.md if you encounter any issues.

---

Next Steps

• Configure your app: Edit .env for mail, queues, etc.
• Set up monitoring: Add your preferred monitoring tools
• Configure backups: Automate backup.sh with cron
• Review security: Check DOCKER.md for hardening tips

🐳 Docker Architecture

Technical reference for Docker services and configurations.

---

Stack Overview

Services:

• webserver (Nginx) — HTTP/HTTPS, reverse proxy to PHP-FPM
• app (PHP 8.4-FPM) — Laravel application runtime
• db (MySQL 8.0) — Database
• caching (Redis 7) — Cache, sessions, queues
• supervisor — Background workers (Horizon)
• scheduler — Cron jobs (Laravel scheduler)
• certbot — SSL certificate management

Service Flow:

Internet → webserver:80/443 → app (PHP-FPM)
                                ├─→ db (MySQL)
                                └─→ caching (Redis)

certbot → webserver (SSL certificates)
supervisor → app (background jobs)
scheduler → app (cron tasks)

---

Docker Compose Files

Structure:

docker-compose.yaml       # Base (shared config)
docker-compose.dev.yaml   # Development overrides
docker-compose.prod.yaml  # Production overrides

Development:

docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up

• Ports exposed (3306, 6379, 5173)
• Debug enabled
• Self-signed SSL
• Vite HMR enabled

Production:

docker compose -f docker-compose.yaml -f docker-compose.prod.yaml up

• No exposed ports except 80/443
• Debug disabled
• Let's Encrypt SSL
• HTTPS redirect enabled

---

Services

App (PHP-FPM)

Image: php:8.4-fpm

Includes: Composer, Node.js 20, MySQL client

PHP Extensions:

• gd, exif, opcache
• pdo_mysql, pcntl, zip, fileinfo
• redis (PECL)

Configuration:

• docker/php/php.ini — PHP settings
• docker/php/opcache.dev.ini — Dev (instant revalidation)
• docker/php/opcache.prod.ini — Prod (no revalidation)

---

Webserver (Nginx)

Image: nginx:alpine

Features:

• Dynamic config via environment variables
• Cloudflare real IP detection
• Gzip compression
• Security headers (HSTS, X-Frame-Options, etc.)
• Rate limiting

Configuration:

• docker/nginx/nginx.conf — Main config
• docker/nginx/fpm-template.conf — Site template
• docker/nginx/entrypoint.sh — Env substitution

---

Database (MySQL)

Image: mysql:8.0

Key Settings:

character-set-server=utf8mb4
innodb_buffer_pool_size=256M
slow_query_log=1
long_query_time=2

View slow queries:

docker compose exec db tail -f /var/log/mysql/slow.log

Tuning by RAM:

• 2GB: innodb_buffer_pool_size=512M
• 4GB: innodb_buffer_pool_size=1G
• 8GB+: innodb_buffer_pool_size=2G

Edit docker/mysql/my.cnf and restart.

---

Caching (Redis)

Image: redis:7-alpine

Configuration:

--appendonly yes              # AOF persistence
--requirepass ${PASSWORD}     # Auth required
--maxmemory 256mb            # Memory limit
--maxmemory-policy allkeys-lru

---

Supervisor

Runs Laravel Horizon for background jobs.

Configuration: docker/supervisor/horizon.conf

Auto-restarts on failure.

---

Scheduler

Runs php artisan schedule:run every 60 seconds.

---

Certbot

Renews SSL certificates every 12 hours automatically.

Checks validity, renews if < 30 days remaining.

---

Network & Volumes

Network

Name: app_network (bridge driver)

Internal DNS:

DB_HOST=db
REDIS_HOST=caching

Services communicate by name within the network.

Volumes

Persistent:

• mysql-data — Database files
• redis-data — Cache persistence

Bind Mounts:

• .:/usr/src/app — Application code
• ./logs/nginx:/var/log/nginx — Logs
• ./data/certbot/conf:/etc/letsencrypt — Certificates

---

Configuration

PHP (docker/php/php.ini)

memory_limit=256M
upload_max_filesize=20M
post_max_size=25M
max_execution_time=60

OPcache

Development: Validates every request

opcache.validate_timestamps=1
opcache.revalidate_freq=0

Production: Never checks (faster)

opcache.validate_timestamps=0

After code changes: docker compose restart app

MySQL (docker/mysql/my.cnf)

Default config is production-ready for 2-4GB RAM servers.

For tuning: edit docker/mysql/my.cnf and restart db service.

---

Customization

Add PHP Extension

Edit docker/php/Dockerfile:

RUN apt-get install -y libmagickwand-dev \
    && pecl install imagick \
    && docker-php-ext-enable imagick

Rebuild: docker compose build --no-cache app && docker compose up -d

Add Service

Add to docker-compose.yaml:

services:
  newservice:
    image: service/image
    networks:
      - app_network
    volumes:
      - newservice-data:/data

Resource Limits

Uncomment in docker-compose.yaml:

deploy:
  resources:
    limits:
      cpus: '2'
      memory: 2G

Useful when running multiple apps on same server.

---

Production Checklist

Before going live:

1. ✅ Run server-setup.sh (configures firewall, Fail2Ban, security)
2. ✅ Set strong passwords in .env (openssl rand -base64 32)
3. ✅ Set up automated backups (crontab -e → add backup.sh)
4. ✅ Test SSL certificate renewal (docker compose exec certbot certbot renew --dry-run)
5. ✅ Enable resource limits if needed (edit docker-compose.yaml)
6. ✅ Configure log rotation (/etc/logrotate.d/)

Post-launch:

• Monitor logs: docker compose logs -f
• Check health: docker compose ps
• Monitor disk space: df -h

---

For common commands, see README.md.

For troubleshooting, see TROUBLESHOOTING.md.

📜 Scripts Reference

Quick reference for all automation scripts.

---

Overview

Script	Purpose	When to Use
deploy.sh	Deploy app (dev/prod)	First deploy, major updates
server-setup.sh	Initialize server	Once per server (as root)
update.sh	Quick updates	After git pull
backup.sh	Database backup	Daily (cron recommended)
laravel-helper.sh	Laravel commands	Interactive menu
create-ssl-certs.sh	Dev SSL certificates	Once for local dev

---

deploy.sh

Main deployment script for dev and production.

Usage:

./scripts/deploy.sh dev   # Development
./scripts/deploy.sh prod  # Production

What it does:

1. Checks prerequisites (Docker, Git)
2. Configures environment (interactive prompts)
3. Detects Cloudflare setup
4. Builds and starts Docker containers
5. Installs dependencies (Composer, NPM)
6. Generates APP_KEY
7. Runs database migrations
8. Sets up SSL (prod only)
9. Optimizes Laravel caches

First run: Takes 3-5 minutes Subsequent runs: Faster (cached layers)

---

server-setup.sh

One-time server initialization with security hardening.

Usage:

# On fresh Ubuntu server (as root)
curl -fsSL https://raw.githubusercontent.com/mg2k4/Dockavel/main/scripts/server-setup.sh | sudo bash

What it does:

1. Updates system packages
2. Installs Docker + Docker Compose
3. Configures UFW firewall (ports 22, 80, 443)
4. Sets up Fail2Ban for SSH protection
5. Creates deploy user with sudo access
6. Enables automatic security updates
7. Hardens SSH (disables root login, password auth)

Duration: ~5 minutes

After running: SSH as deploy user, not root

---

update.sh

Quick updates after pulling new code.

Usage:

cd /var/www/app
git pull origin main
./scripts/update.sh

What it does:

1. Rebuilds containers if Dockerfile changed
2. Installs new dependencies
3. Runs new migrations
4. Clears and rebuilds caches
5. Restarts services

Note: Only rebuilds what changed (fast updates)

---

backup.sh

Database backup with automatic retention.

Usage:

./scripts/backup.sh

What it does:

1. Creates timestamped SQL dump
2. Saves to ./backups/ directory
3. Compresses with gzip
4. Keeps last 7 daily backups
5. Keeps last 4 weekly backups
6. Removes older backups

Backup location: ./backups/db_backup_YYYY-MM-DD_HH-MM-SS.sql.gz

Automate with cron:

# Daily at 2 AM
0 2 * * * cd /var/www/app && ./scripts/backup.sh >> /var/log/backup.log 2>&1

Restore a backup:

gunzip backups/db_backup_2025-01-10_02-00-00.sql.gz
docker compose exec -T db mysql -u root -p${MYSQL_ROOT_PASSWORD} ${DB_DATABASE} < backups/db_backup_2025-01-10_02-00-00.sql

---

laravel-helper.sh

Interactive menu for common Laravel commands.

Usage:

./scripts/laravel-helper.sh

Menu options:

1. Run migrations
2. Rollback migrations
3. Seed database
4. Clear all caches
5. Run queue worker
6. Start Horizon
7. Run Tinker
8. Generate APP_KEY
9. Storage link
10. Run tests
11. Custom Artisan command

Shortcut: Instead of typing docker compose exec app php artisan migrate, just run the helper and choose option 1.

---

create-ssl-certs.sh

Generate self-signed SSL certificates for local development.

Usage:

./scripts/create-ssl-certs.sh

What it does:

1. Creates docker/nginx/dev-cert/ directory
2. Generates self-signed certificate (valid 365 days)
3. Configures for localhost

Note: Browser will show "Not Secure" warning (normal for self-signed certs)

Trust the certificate (optional):

• Mac: Add to Keychain, set to "Always Trust"
• Linux: Add to system certificates
• Windows: Import to "Trusted Root Certification Authorities"

---

Common Tasks

Deploy to production:

ssh deploy@your-server
cd /var/www/app
./scripts/deploy.sh prod

Update production:

ssh deploy@your-server
cd /var/www/app
git pull origin main
./scripts/update.sh

Backup database:

./scripts/backup.sh

Run migrations:

./scripts/laravel-helper.sh  # Choose option 1
# Or directly:
docker compose exec app php artisan migrate

View logs:

docker compose logs -f
docker compose logs -f app  # Just app container

---

Troubleshooting scripts? See TROUBLESHOOTING.md

🔧 Troubleshooting

⚡ One-Liner Diagnostics

# Run this first to get a quick health overview
docker compose ps && echo "---" && docker compose exec app php artisan about --only=environment

🚨 Quick Fixes

Something broke? Try this first:

# 1. Clear caches
docker compose exec app php artisan config:clear
docker compose exec app php artisan cache:clear

# 2. Fix permissions
docker compose exec app chown -R www-data:www-data storage bootstrap/cache
docker compose exec app chmod -R 775 storage bootstrap/cache

# 3. Restart
docker compose restart

# 4. Still broken? Check logs
docker compose logs app --tail=50

📋 Common Issues

"Port already in use"

sudo lsof -i :80
sudo kill -9 <PID>

"Permission denied"

chmod +x *.sh

"Database connection refused"

# Check .env: DB_HOST=db (not localhost!)
docker compose restart db

"502 Bad Gateway"

docker compose restart app webserver

"SSL certificate failed"

# Check DNS points to your server
dig +short your-domain.com

# Ensure ports 80/443 are open
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

🔍 Still stuck?

Run diagnostics:

docker compose ps             # Check status
docker compose logs           # Check logs
./scripts/laravel-helper.sh   # Interactive helper

Need help? Open an issue with:

• Error message
• Output of docker compose logs
• What you tried already

🤝 Contributing

Thanks for considering contributing! 🙏

Quick Start

1. Fork the repo
2. Make your changes
3. Test it works
4. Open a PR

Guidelines

All contributions are welcome — bug fixes, features, documentation improvements, or anything else you think could help.

Don't worry about perfect code or perfect English. What matters is that it works and helps someone.

Questions?

Open an issue or discussion. I typically respond within 24-48h.

Be kind. That's the only rule.