344 lines
8.6 KiB
Markdown
344 lines
8.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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_password`rd: `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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
volumes:
|
|
- ./:/var/www # Live code mounting
|
|
```
|
|
|
|
### Queue Workers
|
|
|
|
Queue workers are running via Supervisor inside the container. To restart:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
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](https://docs.docker.com/compose/)
|
|
- [Laravel Docker Documentation](https://laravel.com/docs/deployment)
|
|
- [PostgreSQL Docker](https://hub.docker.com/_/postgres)
|
|
- [Mailpit Documentation](https://github.com/axllent/mailpit)
|