Teren-app/LOCAL_TESTING_GUIDE.md

Local Testing Guide - Windows/Mac/Linux

This guide helps you test the Teren App Docker setup on your local machine without WireGuard VPN.

Quick Start

1. Prerequisites

• Docker Desktop installed and running
• Git
• 8GB RAM recommended
• Ports available: 8080, 5433 (PostgreSQL), 5050, 6379, 9000, 8025, 1025
• Note: If you have local PostgreSQL on port 5432, the Docker container uses 5433 instead

2. Setup

# Clone repository (if not already)
git clone YOUR_GITEA_URL
cd Teren-app

# Copy local environment file
cp .env.local.example .env

# Start all services
docker compose -f docker-compose.local.yaml up -d

# Wait for services to start (30 seconds)
timeout 30

# Generate application key
docker compose -f docker-compose.local.yaml exec app php artisan key:generate

# Run migrations
docker compose -f docker-compose.local.yaml exec app php artisan migrate

# Seed database (optional)
docker compose -f docker-compose.local.yaml exec app php artisan db:seed

# Install frontend dependencies (if needed)
npm install
npm run dev

3. Access Services

Service	URL	Credentials
Laravel App	http://localhost:8080	-
Portainer	http://localhost:9000	Set on first visit
pgAdmin	http://localhost:5050	admin@local.dev / admin
Mailpit	http://localhost:8025	-
PostgreSQL	localhost:5433	teren_user / local_password
Redis	localhost:6379	-

Note: PostgreSQL uses port 5433 to avoid conflicts with any local PostgreSQL installation.

Common Commands

Docker Compose Commands

# Start all services
docker compose -f docker-compose.local.yaml up -d

# Stop all services
docker compose -f docker-compose.local.yaml down

# View logs
docker compose -f docker-compose.local.yaml logs -f

# View specific service logs
docker compose -f docker-compose.local.yaml logs -f app

# Restart a service
docker compose -f docker-compose.local.yaml restart app

# Rebuild containers
docker compose -f docker-compose.local.yaml up -d --build

# Stop and remove everything (including volumes)
docker compose -f docker-compose.local.yaml down -v

Laravel Commands

# Run artisan commands
docker compose -f docker-compose.local.yaml exec app php artisan [command]

# Examples:
docker compose -f docker-compose.local.yaml exec app php artisan migrate
docker compose -f docker-compose.local.yaml exec app php artisan db:seed
docker compose -f docker-compose.local.yaml exec app php artisan cache:clear
docker compose -f docker-compose.local.yaml exec app php artisan config:clear
docker compose -f docker-compose.local.yaml exec app php artisan queue:work

# Run tests
docker compose -f docker-compose.local.yaml exec app php artisan test

# Access container shell
docker compose -f docker-compose.local.yaml exec app sh

# Run Composer commands
docker compose -f docker-compose.local.yaml exec app composer install
docker compose -f docker-compose.local.yaml exec app composer update

Database Commands

# Connect to PostgreSQL (from inside container)
docker compose -f docker-compose.local.yaml exec postgres psql -U teren_user -d teren_app

# Connect from Windows host
psql -h localhost -p 5433 -U teren_user -d teren_app

# Backup database
docker compose -f docker-compose.local.yaml exec postgres pg_dump -U teren_user teren_app > backup.sql

# Restore database
docker compose -f docker-compose.local.yaml exec -T postgres psql -U teren_user teren_app < backup.sql

# Reset database
docker compose -f docker-compose.local.yaml exec app php artisan migrate:fresh --seed

pgAdmin Setup

1. Open http://localhost:5050
2. Login: admin@local.dev / admin
3. Add Server:
   • General Tab:
     • Name: Teren Local
   • Connection Tab:
     • Host: postgres
     • Port: 5432
     • Database: teren_app
     • Username: teren_user
     • Passwo

External Connection: To connect from your Windows machine (e.g., DBeaver, pgAdmin desktop), use:

• Host: localhost
• Port: 5433 (not 5432)
• Database: teren_app
• Username: teren_user
• Password: local_passwordrd: local_password

4. Click Save

Mailpit - Email Testing

All emails sent by the application are caught by Mailpit.

• Access: http://localhost:8025
• View all emails in the web interface
• Test email sending:

docker compose -f docker-compose.local.yaml exec app php artisan tinker
# In tinker:
Mail::raw('Test email', function($msg) {
    $msg->to('test@example.com')->subject('Test');
});

Portainer Setup

1. Open http://localhost:9000
2. On first visit, create admin account
3. Select "Docker" environment
4. Click "Connect"

Use Portainer to:

• View and manage containers
• Check logs
• Execute commands in containers
• Monitor resource usage

Development Workflow

Frontend Development

The local setup supports live reloading:

# Run Vite dev server (outside Docker)
npm run dev

# Or inside Docker
docker compose -f docker-compose.local.yaml exec app npm run dev

Access: http://localhost:8080

Code Changes

All code changes are automatically reflected because the source code is mounted as a volume:

volumes:
  - ./:/var/www  # Live code mounting

Queue Workers

Queue workers are running via Supervisor inside the container. To restart:

# Restart queue workers
docker compose -f docker-compose.local.yaml exec app supervisorctl restart all

# Check status
docker compose -f docker-compose.local.yaml exec app supervisorctl status

# View worker logs
docker compose -f docker-compose.local.yaml exec app tail -f storage/logs/worker.log

Troubleshooting

Port Already in Use

If you get "port is already allocated" error:

# Windows - Find process using port
netstat -ano | findstr :8080

# Kill process by PID
taskkill /PID <PID> /F

# Or change port in docker-compose.local.yaml
ports:
  - "8081:80"  # Change 8080 to 8081

Container Won't Start

# Check logs
docker compose -f docker-compose.local.yaml logs app

# Rebuild containers
docker compose -f docker-compose.local.yaml down
docker compose -f docker-compose.local.yaml up -d --build

Permission Errors (Linux/Mac)

# Fix storage permissions
docker compose -f docker-compose.local.yaml exec app chown -R www:www /var/www/storage
docker compose -f docker-compose.local.yaml exec app chmod -R 775 /var/www/storage

Database Connection Failed

# Check if PostgreSQL is running
docker compose -f docker-compose.local.yaml ps postgres

# Check logs
docker compose -f docker-compose.local.yaml logs postgres

# Restart PostgreSQL
docker compose -f docker-compose.local.yaml restart postgres

Clear All Data and Start Fresh

# Stop and remove everything
docker compose -f docker-compose.local.yaml down -v

# Remove images
docker compose -f docker-compose.local.yaml down --rmi all

# Start fresh
docker compose -f docker-compose.local.yaml up -d --build

# Re-initialize
docker compose -f docker-compose.local.yaml exec app php artisan key:generate
docker compose -f docker-compose.local.yaml exec app php artisan migrate:fresh --seed

Performance Tips

Windows Performance

If using WSL2 (recommended):

1. Clone repo inside WSL2 filesystem, not Windows filesystem
2. Use WSL2 terminal for commands
3. Enable WSL2 integration in Docker Desktop settings

Mac Performance

1. Enable VirtioFS in Docker Desktop settings
2. Disable file watching if not needed
3. Use Docker volumes for vendor directories:

volumes:
  - ./:/var/www
  - /var/www/vendor  # Anonymous volume for vendor
  - /var/www/node_modules  # Anonymous volume for node_modules

Testing Production-Like Setup

To test the production VPN setup locally (advanced):

1. Enable WireGuard in docker-compose.yaml.example
2. Change all 10.13.13.1 bindings to 127.0.0.1
3. Test SSL with self-signed certificates

Differences from Production

Feature	Local	Production
VPN	No VPN	WireGuard required
Port	:8080	:80/:443
SSL	No SSL	Let's Encrypt
Debug	Enabled	Disabled
Emails	Mailpit	Real SMTP
Logs	Debug level	Error level
Code	Live mount	Built into image

Next Steps

After testing locally:

1. Review docker-compose.yaml.example for production
2. Follow DEPLOYMENT_GUIDE.md for VPS setup
3. Configure WireGuard VPN
4. Deploy to production

Useful Resources

• Docker Compose Documentation
• Laravel Docker Documentation
• PostgreSQL Docker
• Mailpit Documentation