From 0a3ada6109b3fb75c4e2c4cf90062bd36f47e867 Mon Sep 17 00:00:00 2001 From: TheMaddax Date: Wed, 11 Dec 2024 20:25:00 -0600 Subject: [PATCH] Initial commit: Add technology stack --- .env | 2 + DeafGain_Tech_Stack | 76 ++++++++++++++++ README.md | 92 +++++++++++++++++++ Statistics-plan.html | 176 +++++++++++++++++++++++++++++++++++ TECH_PLAN | 212 +++++++++++++++++++++++++++++++++++++++++++ docker-compose.yml | 59 ++++++++++++ 6 files changed, 617 insertions(+) create mode 100644 .env create mode 100644 DeafGain_Tech_Stack create mode 100644 README.md create mode 100644 Statistics-plan.html create mode 100644 TECH_PLAN create mode 100644 docker-compose.yml diff --git a/.env b/.env new file mode 100644 index 0000000..1adb661 --- /dev/null +++ b/.env @@ -0,0 +1,2 @@ +MYSQL_ROOT_PASSWORD=change_this_root_password +MYSQL_PASSWORD=change_this_matomo_password diff --git a/DeafGain_Tech_Stack b/DeafGain_Tech_Stack new file mode 100644 index 0000000..1c850cd --- /dev/null +++ b/DeafGain_Tech_Stack @@ -0,0 +1,76 @@ +## Tech Stack + +### Frontend +- React 19 +- TypeScript 5.7 +- React Router DOM 7 +- Tailwind CSS 3.4 +- Framer Motion 11 +- React Icons 5.4 +- React Simple Maps 4.0 (beta) +- React Intersection Observer 9.13 +- Next.js 14.1 + +### Backend +- Node.js with Express 4.21 +- TypeScript +- Nodemailer 6.9 for email handling +- CORS for cross-origin resource sharing +- dotenv 16.4 for environment variable management +- Upstash Redis 1.28 for caching/rate limiting + +### Development & Build Tools +- Docker & Docker Compose +- PostCSS 8.4 +- Autoprefixer 10.4 +- pnpm 9.14 (package manager) +- Vite 6.0 +- ESLint 9 +- Concurrently for running multiple processes +- tsx/ts-node for TypeScript execution +- Hot module replacement (HMR) + +### Production +- Nginx (Production server for frontend) +- Node.js server for backend API + +### Architecture +- Frontend running on port 3000 (development) +- Backend API running on port 4000 +- Containerized development and production environments +- REST API for contact form handling +- Gmail SMTP for email delivery +- Rate limiting implementation +- Context-based state management +- Redis-backed caching layer + +### Key Features +- Responsive design +- Animated UI components with Framer Motion +- Interactive USA region map +- Contact form with email notifications +- Timeline visualization +- Service showcase +- Biography section +- Testimonials section +- Video playback with WebVTT subtitles +- Transcription support +- Toast notification system +- Snow peaks animation effect +- Custom video player component + +### Development Environment +- Multi-container setup with Docker Compose +- Hot-reloading enabled +- Separate development and production builds +- Environment variable management for sensitive data +- TypeScript configuration for both client and server +- Concurrent development server (frontend + backend) + +### Production Environment +- Nginx serving static frontend files +- Node.js backend API +- Containerized deployment +- Secure email handling with Google App credentials +- Multi-stage Docker builds +- Production-optimized builds with tree-shaking \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..0ff1bd9 --- /dev/null +++ b/README.md @@ -0,0 +1,92 @@ +# Matomo Analytics Setup + +This repository contains the Docker configuration for running Matomo Analytics in production. + +## Prerequisites + +- Docker +- Docker Compose +- At least 2GB of RAM +- 20GB+ storage space + +## Setup Instructions + +1. Configure environment variables: + - Edit `.env` file and set secure passwords for: + - MYSQL_ROOT_PASSWORD + - MYSQL_PASSWORD + +2. Start the containers: + ```bash + docker compose up -d + ``` + +3. Access Matomo: + - Open http://localhost:8080 + - Follow the installation wizard + - Use these database settings: + - Server: db + - Login: matomo + - Password: (value of MYSQL_PASSWORD from .env) + - Database Name: matomo + +## Production Configuration + +### Security +- Change default admin password +- Enable 2FA for admin accounts +- Configure trusted hosts in config.ini.php +- Set up SSL/TLS termination via reverse proxy + +### Performance +- Database is configured with: + - max-allowed-packet: 64MB + - PHP memory limit: 512MB +- Adjust these values in docker-compose.yml if needed + +### Maintenance +- Backup volumes regularly: + - matomo_db: Database data + - matomo_data: Matomo files + - matomo_config: Configuration +- Monitor container health: + ```bash + docker compose ps + docker compose logs + ``` + +### Updating +1. Pull new images: + ```bash + docker compose pull + ``` +2. Restart containers: + ```bash + docker compose down + docker compose up -d + ``` + +## Troubleshooting + +### Database Connection Issues +- Verify database credentials in .env +- Check database container logs: + ```bash + docker compose logs db + ``` + +### Performance Issues +- Monitor resource usage: + ```bash + docker stats + ``` +- Adjust PHP memory limit if needed +- Consider enabling caching + +### Container Health +Both containers have health checks configured: +- Database: Checks MySQL connection +- Matomo: Checks HTTP response +Monitor health status: +```bash +docker compose ps diff --git a/Statistics-plan.html b/Statistics-plan.html new file mode 100644 index 0000000..321623d --- /dev/null +++ b/Statistics-plan.html @@ -0,0 +1,176 @@ + + + + + + Multi-Site Analytics Tech Stack Overview + + + +

Multi-Site Analytics Technology Stack

+ +
+ Complete technology stack for enterprise-grade multi-site analytics system +
+ +
+

Core Technology Stack

+
+Technology Overview +├── Frontend Layer +│ ├── Next.js (Dashboard Interface) +│ ├── React (Component Architecture) +│ ├── TypeScript +│ └── Tailwind CSS +│ +├── Backend Services +│ ├── Matomo Analytics Engine +│ ├── MariaDB/MySQL +│ ├── Node.js API Services +│ └── JWT Authentication +│ +├── Infrastructure +│ ├── Docker & Docker Compose +│ ├── Portainer CE +│ ├── Caddy Server +│ └── Gitea +│ +└── Development Tools + ├── Local Dev Environment + ├── Hot Reload + ├── Testing Framework + └── CI/CD Pipeline
+
+ +
+

Service Architecture

+
+Service Layout +├── Analytics Engine (Matomo) +│ ├── Website ID: deafmissoula.org +│ ├── Website ID: chrishaulmark.com +│ ├── Website ID: deafgain.sigd.net +│ └── Website ID: finlion.sigd.net +│ +├── Database Layer +│ ├── MariaDB Primary +│ └── Automated Backups +│ +├── Access Control +│ ├── JWT Authentication +│ ├── Role-Based Access +│ └── Individual Dashboards +│ +└── Monitoring + ├── Container Health + ├── Resource Usage + ├── Performance Metrics + └── Security Logs
+
+ +
+

Network Architecture

+
+Network Layout +├── External Traffic +│ └── Caddy (SSL Termination) +│ +├── Internal Networks +│ ├── caddy_network +│ │ ├── Website Containers +│ │ └── Analytics Dashboard +│ │ +│ ├── analytics_network +│ │ ├── Matomo +│ │ └── MariaDB +│ │ +│ └── gitea_network +│ ├── Gitea +│ └── MariaDB +│ +└── Monitoring Network + ├── Portainer + └── Health Checks
+
+ +
+

Features Per Website

+
+Dashboard Features +├── Real-Time Analytics +│ ├── Visitor Statistics +│ ├── Page Views +│ ├── User Behavior +│ └── Heatmaps +│ +├── Reporting +│ ├── Custom Date Ranges +│ ├── Data Export +│ ├── Referrer Tracking +│ └── E-commerce Tracking +│ +└── Administration + ├── User Management + ├── Access Control + ├── API Integration + └── GDPR Tools
+
+ +
+

Deployment & Operations

+
+Operations Flow +├── Deployment +│ ├── Gitea Push +│ ├── Automated Tests +│ └── Container Updates +│ +├── Maintenance +│ ├── Daily Backups +│ ├── Security Updates +│ ├── Log Archiving +│ └── Performance Monitoring +│ +└── Scaling + ├── Resource Management + ├── Load Balancing + └── Capacity Planning
+
+ +
+ Implementation Note: Each website gets its own isolated analytics instance while sharing the underlying infrastructure for cost efficiency. Matomo provides enhanced privacy features and GDPR compliance tools. +
+ + \ No newline at end of file diff --git a/TECH_PLAN b/TECH_PLAN new file mode 100644 index 0000000..f523c18 --- /dev/null +++ b/TECH_PLAN @@ -0,0 +1,212 @@ +# Statistics Engine Technical Plan + +## 1. Infrastructure Overview + +### Docker Container Stack +- Matomo Analytics Container + - Official Matomo image + - Exposed port: 8080 + - Environment: Production + +- MariaDB Database Container + - Version: Latest stable + - Persistent volume for data + - Restricted network access + +- Dashboard Frontend Container + - Next.js application + - TypeScript + React + - Tailwind CSS for styling + - Exposed port: 3001 + +- Existing Infrastructure Integration + - Portainer (10.4.0.206:9443) + - Caddy reverse proxy + - Gitea (gitea.sigd.net) + +## 2. Authentication System + +### Google Workspace Integration +- Domain: deafgain.org +- Primary Admin: system@deafgain.org +- Authentication Method: Google OAuth 2.0 +- Security: APP password implementation +- Scope: email, profile + +## 3. Component Details + +### A. Matomo Analytics Setup +1. Core Configuration + - Database: MariaDB + - Data retention policy + - API access configuration + - Website tracking setup + - GDPR compliance tools + +2. Security Measures + - API token management + - Rate limiting + - Access control lists + - IP anonymization + +### B. Dashboard Frontend +1. Technical Stack + - Next.js 14.1 + - React 19 + - TypeScript 5.7 + - Tailwind CSS 3.4 + +2. Features + - Real-time statistics display + - Historical data visualization + - Custom date range selection + - Export capabilities + - Mobile-responsive design + - Heatmaps and session recordings + - E-commerce tracking + +3. API Integration + - Matomo HTTP API + - Data fetching strategy + - Error handling + - Caching implementation + - Custom dimension support + +### C. Database Layer +1. MariaDB Configuration + - Data structure optimization + - Automated backup strategy + - Performance tuning + - Connection pooling + - Table partitioning + +## 4. Network Configuration + +### Caddy Setup +```caddyfile +deafgain.org { + handle /control* { + reverse_proxy localhost:3001 + } + + handle /analytics* { + reverse_proxy localhost:8080 + } +} +``` + +### Docker Networks +1. Frontend Network + - Dashboard container + - Caddy reverse proxy + +2. Backend Network + - Matomo container + - MariaDB container + +## 5. Implementation Steps + +### Phase 1: Infrastructure Setup +1. Create Docker networks +2. Deploy MariaDB container +3. Configure persistent volumes +4. Set up backup system + +### Phase 2: Matomo Deployment +1. Deploy Matomo container +2. Configure database connection +3. Set up initial website tracking +4. Configure privacy settings +5. Test data collection + +### Phase 3: Dashboard Development +1. Create Next.js application +2. Implement Google OAuth +3. Develop statistics interface +4. Connect to Matomo API +5. Implement custom reports + +### Phase 4: Integration +1. Configure Caddy routing +2. Set up SSL certificates +3. Implement security measures +4. Test end-to-end functionality + +## 6. Website Integration + +### DeafGain Website Modification +- Add Matomo tracking code to head section: +```javascript + + + +``` + +## 7. Monitoring and Maintenance + +### Health Checks +- Container status monitoring +- Database performance metrics +- API response times +- Error rate tracking +- Resource usage monitoring + +### Backup Strategy +- Daily database backups +- Configuration backups +- Disaster recovery plan +- Archive logs rotation + +## 8. Security Considerations + +### Access Control +- Role-based access control +- API token management +- Rate limiting +- IP whitelisting +- Two-factor authentication + +### Data Protection +- SSL/TLS encryption +- Database encryption +- Regular security audits +- GDPR compliance tools +- Cookie consent management +- Data anonymization + +## 9. Future Enhancements + +### Potential Features +- Custom metrics tracking +- Advanced segment analysis +- A/B testing integration +- Enhanced e-commerce tracking +- Custom alert system +- Automated reporting + +## 10. Documentation Requirements + +### Technical Documentation +- System architecture +- API documentation +- Deployment procedures +- Troubleshooting guides +- Performance optimization + +### User Documentation +- Dashboard usage guide +- Authentication procedures +- Report generation +- Data interpretation +- Privacy settings management diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000..672cf0c --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,59 @@ +version: '3' + +services: + db: + image: mariadb:10.11 + command: --max-allowed-packet=64MB + restart: always + volumes: + - matomo_db:/var/lib/mysql + environment: + - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD} + - MYSQL_PASSWORD=${MYSQL_PASSWORD} + - MYSQL_DATABASE=matomo + - MYSQL_USER=matomo + networks: + - matomo_network + healthcheck: + test: ["CMD", "mysqladmin", "ping", "-h", "localhost"] + interval: 30s + timeout: 10s + retries: 5 + + matomo: + image: matomo:5-apache + restart: always + volumes: + - matomo_data:/var/www/html + - matomo_config:/var/www/html/config + environment: + - MATOMO_DATABASE_HOST=db + - MATOMO_DATABASE_DBNAME=matomo + - MATOMO_DATABASE_USERNAME=matomo + - MATOMO_DATABASE_PASSWORD=${MYSQL_PASSWORD} + - MATOMO_DATABASE_TABLES_PREFIX=matomo_ + - PHP_MEMORY_LIMIT=512M + - MATOMO_ENABLE_FORCE_SSL=1 + ports: + - "8080:80" + depends_on: + - db + networks: + - matomo_network + healthcheck: + test: ["CMD", "curl", "-f", "http://localhost:80"] + interval: 30s + timeout: 10s + retries: 5 + +volumes: + matomo_db: + driver: local + matomo_data: + driver: local + matomo_config: + driver: local + +networks: + matomo_network: + driver: bridge