Initial commit
This commit is contained in:
Ronald Huynen
314
references/EXTERNAL_SERVICES_REQUIREMENTS.md
Normal file
314
references/EXTERNAL_SERVICES_REQUIREMENTS.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# Timebank.cc - External Services Requirements
|
||||
|
||||
This document outlines all external services, dependencies, and infrastructure requirements needed to run the Timebank.cc application.
|
||||
|
||||
## Core Runtime Requirements
|
||||
|
||||
### PHP
|
||||
- **Version**: PHP 8.0+ (required by Laravel 10.x)
|
||||
- **Recommended**: PHP 8.3 for best performance and latest features
|
||||
- **Required Extensions**:
|
||||
- `curl`, `dom`, `gd`, `json`, `mbstring`, `openssl`, `pcre`, `pdo`, `tokenizer`, `xml`, `zip`
|
||||
- `redis` - For cache and queue operations
|
||||
- `mysql`/`mysqli` - For database connectivity
|
||||
- `bcmath` - For precise financial calculations
|
||||
- `intl` - For multi-language support
|
||||
|
||||
### Web Server
|
||||
- **Apache 2.4+** or **Nginx 1.18+**
|
||||
- **SSL/TLS** support required for production
|
||||
- **Rewrite rules** enabled for clean URLs
|
||||
|
||||
## Database Services
|
||||
|
||||
### MySQL/MariaDB (Primary Database)
|
||||
- **MySQL**: 8.0+ (required for window functions in transaction balance calculations)
|
||||
- **MariaDB**: 10.2+ (required for window function support)
|
||||
- **Configuration Requirements**:
|
||||
- UTF8MB4 character set support
|
||||
- Large packet size for media uploads (`max_allowed_packet >= 64MB`)
|
||||
- InnoDB storage engine
|
||||
- **Special Database User Permissions**:
|
||||
- Transaction table has restricted DELETE/UPDATE permissions at MySQL user level
|
||||
- Single application user with table-level restrictions to enforce transaction immutability
|
||||
|
||||
### Database Connection
|
||||
```env
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=timebank_cc
|
||||
DB_USERNAME=timebank_user
|
||||
DB_PASSWORD=secure_password
|
||||
```
|
||||
|
||||
## Cache & Session Storage
|
||||
|
||||
### Redis (Required)
|
||||
- **Version**: Redis 6.0+ recommended
|
||||
- **Usage**:
|
||||
- Session storage (`SESSION_DRIVER=redis`)
|
||||
- Application cache (`CACHE_DRIVER=redis`)
|
||||
- Queue backend (`QUEUE_CONNECTION=redis`)
|
||||
- Real-time presence tracking (online status)
|
||||
|
||||
### Redis Configuration
|
||||
```env
|
||||
REDIS_HOST=127.0.0.1
|
||||
REDIS_PASSWORD=
|
||||
REDIS_PORT=6379
|
||||
REDIS_CACHE_DB=1
|
||||
```
|
||||
|
||||
## Search Service
|
||||
|
||||
### Elasticsearch (Required)
|
||||
- **Version**: Elasticsearch 7.x or 8.x
|
||||
- **Usage**: Full-text search with Scout integration
|
||||
- **Features**:
|
||||
- Multi-language search (en, nl, de, es, fr)
|
||||
- Configurable field boosting
|
||||
- Geographic search capabilities
|
||||
- **Memory Requirements**: Minimum 2GB RAM allocated to Elasticsearch
|
||||
- **Configuration**:
|
||||
```env
|
||||
ELASTICSEARCH_HOST=localhost:9200
|
||||
SCOUT_DRIVER=matchish-elasticsearch
|
||||
```
|
||||
|
||||
### Search Indices
|
||||
The application uses multiple Elasticsearch indices:
|
||||
- `posts_index` - Blog posts and events
|
||||
- `users_index` - User profiles
|
||||
- `organizations_index` - Organization profiles
|
||||
- `banks_index` - Bank profiles
|
||||
|
||||
## Real-time Communication
|
||||
|
||||
### Laravel Reverb WebSocket Server (Required)
|
||||
- **Laravel Reverb**: WebSocket server (Laravel package)
|
||||
- **Port**: 8080 (configurable)
|
||||
- **Usage**:
|
||||
- Real-time messaging via WireChat package
|
||||
- Live notifications
|
||||
- Presence system (online status tracking)
|
||||
- Livewire real-time updates
|
||||
|
||||
### WebSocket Configuration
|
||||
```env
|
||||
BROADCAST_DRIVER=reverb
|
||||
PUSHER_APP_ID=local-app-id
|
||||
PUSHER_APP_KEY=local-app-key
|
||||
PUSHER_APP_SECRET=local-app-secret
|
||||
PUSHER_HOST=localhost
|
||||
PUSHER_PORT=8080
|
||||
PUSHER_SCHEME=http
|
||||
```
|
||||
|
||||
### Starting WebSocket Server
|
||||
```bash
|
||||
php artisan reverb:start
|
||||
```
|
||||
|
||||
## Queue Processing
|
||||
|
||||
### Queue Worker (Required)
|
||||
- **Backend**: Redis-based queues
|
||||
- **Usage**:
|
||||
- Email processing
|
||||
- Background job processing
|
||||
- File uploads and processing
|
||||
- Search index updates
|
||||
|
||||
### Queue Configuration
|
||||
```env
|
||||
QUEUE_CONNECTION=redis
|
||||
QUEUE_DRIVER=redis
|
||||
```
|
||||
|
||||
### Starting Queue Worker
|
||||
```bash
|
||||
php artisan queue:work
|
||||
```
|
||||
|
||||
## Email Services
|
||||
|
||||
### SMTP Server (Required for Production)
|
||||
- **Development**: Mailtrap, MailHog, or similar testing service
|
||||
- **Production**: Any SMTP provider (SendGrid, Mailgun, AWS SES, etc.)
|
||||
|
||||
### Email Configuration
|
||||
```env
|
||||
MAIL_MAILER=smtp
|
||||
MAIL_HOST=smtp.provider.com
|
||||
MAIL_PORT=587
|
||||
MAIL_USERNAME=username
|
||||
MAIL_PASSWORD=password
|
||||
MAIL_ENCRYPTION=tls
|
||||
MAIL_FROM_ADDRESS=noreply@timebank.cc
|
||||
```
|
||||
|
||||
## File Storage & Media
|
||||
|
||||
### File Storage
|
||||
- **Local Storage**: Default for development
|
||||
- **Cloud Storage**: AWS S3, DigitalOcean Spaces, or compatible for production
|
||||
- **Media Library**: Spatie Media Library for file management
|
||||
- **Requirements**:
|
||||
- Image processing: GD or Imagick PHP extension
|
||||
- Max file size: 12MB (configurable)
|
||||
- Supported formats: jpg, jpeg, png, gif, webp, pdf, documents
|
||||
|
||||
### Storage Configuration
|
||||
```env
|
||||
FILESYSTEM_DRIVER=local # or s3 for production
|
||||
AWS_ACCESS_KEY_ID=
|
||||
AWS_SECRET_ACCESS_KEY=
|
||||
AWS_DEFAULT_REGION=
|
||||
AWS_BUCKET=
|
||||
```
|
||||
|
||||
## Frontend Build Tools
|
||||
|
||||
### Node.js & npm (Development)
|
||||
- **Node.js**: 16.x+ LTS
|
||||
- **npm**: 8.x+
|
||||
- **Usage**:
|
||||
- Asset compilation (Vite)
|
||||
- TailwindCSS processing
|
||||
- JavaScript bundling
|
||||
|
||||
### Frontend Dependencies
|
||||
- **Alpine.js**: Client-side reactivity
|
||||
- **TailwindCSS**: Utility-first CSS framework
|
||||
- **Vite**: Modern asset bundling and development server
|
||||
|
||||
### Build Commands
|
||||
```bash
|
||||
npm run dev # Development server with hot module replacement
|
||||
npm run build # Production build
|
||||
npm run prod # Production build (alias)
|
||||
npm run production # Production build (alias)
|
||||
```
|
||||
|
||||
## Optional Services
|
||||
|
||||
### Location Services
|
||||
- **IP Geolocation**: For user location detection
|
||||
- **APIs**: Various location lookup services (configurable)
|
||||
```env
|
||||
LOCATION_TESTING=true
|
||||
```
|
||||
|
||||
### Development Tools
|
||||
- **Laravel Debugbar**: Development debugging
|
||||
- **Laravel Telescope**: Application monitoring (optional)
|
||||
- **Laradumps**: Enhanced debugging
|
||||
|
||||
### Monitoring & Analytics
|
||||
- **Activity Logger**: Built-in user activity tracking (no external services, only for security / debugging)
|
||||
- **Search Analytics**: Search pattern tracking (optional)
|
||||
|
||||
## Environment-Specific Requirements
|
||||
|
||||
### Development Environment
|
||||
- **PHP**: 8.0+ with Xdebug
|
||||
- **Database**: Local MySQL/MariaDB
|
||||
- **Redis**: Local Redis instance
|
||||
- **Elasticsearch**: Local Elasticsearch instance
|
||||
- **WebSocket**: Laravel Reverb on localhost
|
||||
- **Mail**: Mailtrap or MailHog
|
||||
|
||||
### Production Environment
|
||||
- **PHP**: 8.1+ with OPcache enabled
|
||||
- **Database**: MySQL 8.0+ with replication (recommended)
|
||||
- **Redis**: Redis cluster for high availability
|
||||
- **Elasticsearch**: Multi-node cluster with proper memory allocation
|
||||
- **WebSocket**: Laravel Reverb with process management (Supervisor)
|
||||
- **Queue**: Multiple queue workers with Supervisor
|
||||
- **Load Balancer**: For multiple app instances
|
||||
- **SSL Certificate**: Required for WebSocket and general security
|
||||
|
||||
## Deployment Considerations
|
||||
|
||||
### Process Management (Production)
|
||||
- **Supervisor**: For queue workers and WebSocket server
|
||||
- **Process monitoring**: Ensure critical services restart on failure
|
||||
|
||||
### Example Supervisor Configuration
|
||||
```ini
|
||||
[program:timebank-queue]
|
||||
process_name=%(program_name)s_%(process_num)02d
|
||||
command=php /var/www/timebank/artisan queue:work redis --sleep=3 --tries=3
|
||||
directory=/var/www/timebank
|
||||
user=www-data
|
||||
numprocs=8
|
||||
|
||||
[program:timebank-reverb]
|
||||
process_name=%(program_name)s
|
||||
command=php /var/www/timebank/artisan reverb:start
|
||||
directory=/var/www/timebank
|
||||
user=www-data
|
||||
```
|
||||
|
||||
### Security Requirements
|
||||
- **Firewall**: Ports 80, 443, 8080 (WebSocket)
|
||||
- **SSL/TLS**: Required for production
|
||||
- **Database Security**: Restricted user permissions
|
||||
- **File Permissions**: Proper Laravel directory permissions
|
||||
|
||||
### Performance Optimization
|
||||
- **OPcache**: PHP bytecode caching
|
||||
- **Redis**: Memory-based caching
|
||||
- **CDN**: For static assets (optional)
|
||||
- **Database Indexing**: Proper indexes for large datasets
|
||||
|
||||
## Container Deployment (Optional)
|
||||
|
||||
### Docker Services
|
||||
If using containerization, the following services are needed:
|
||||
|
||||
- **App Container**: PHP-FPM with required extensions
|
||||
- **Web Server**: Nginx or Apache
|
||||
- **Database**: MySQL 8.0+ container
|
||||
- **Redis**: Redis container
|
||||
- **Elasticsearch**: Elasticsearch container
|
||||
- **Queue Worker**: Dedicated container for queue processing
|
||||
- **WebSocket**: Container for Reverb WebSocket server
|
||||
|
||||
### Docker Compose Example Structure
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
# PHP application
|
||||
nginx:
|
||||
# Web server
|
||||
mysql:
|
||||
# Database
|
||||
redis:
|
||||
# Cache & sessions
|
||||
elasticsearch:
|
||||
# Search service
|
||||
queue:
|
||||
# Queue worker
|
||||
websocket:
|
||||
# Reverb server
|
||||
```
|
||||
|
||||
## Minimum System Resources
|
||||
|
||||
### Development
|
||||
- **CPU**: 2 cores
|
||||
- **RAM**: 4GB (2GB for app, 2GB for services)
|
||||
- **Storage**: 10GB
|
||||
|
||||
### Production (Small)
|
||||
- **CPU**: 4 cores
|
||||
- **RAM**: 8GB (4GB for app, 2GB for Redis, 2GB for Elasticsearch)
|
||||
- **Storage**: 50GB+ with SSD
|
||||
|
||||
### Production (Medium)
|
||||
- **CPU**: 8 cores
|
||||
- **RAM**: 16GB
|
||||
- **Storage**: 100GB+ SSD
|
||||
- **Network**: Load balancer, CDN integration
|
||||
Reference in New Issue
Block a user