{"id":28766853,"url":"https://github.com/danjamk/matomo-aws-server","last_synced_at":"2025-07-31T18:33:26.505Z","repository":{"id":298936557,"uuid":"1001165014","full_name":"danjamk/matomo-aws-server","owner":"danjamk","description":"This project deploys an AWS EC2 server with Matomo web analytics server","archived":false,"fork":false,"pushed_at":"2025-06-13T17:57:41.000Z","size":54,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-13T18:25:59.804Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/danjamk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-12T23:44:56.000Z","updated_at":"2025-06-13T17:57:44.000Z","dependencies_parsed_at":"2025-06-13T18:36:22.501Z","dependency_job_id":null,"html_url":"https://github.com/danjamk/matomo-aws-server","commit_stats":null,"previous_names":["danjamk/matomo-aws-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/danjamk/matomo-aws-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjamk%2Fmatomo-aws-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjamk%2Fmatomo-aws-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjamk%2Fmatomo-aws-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjamk%2Fmatomo-aws-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/danjamk","download_url":"https://codeload.github.com/danjamk/matomo-aws-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/danjamk%2Fmatomo-aws-server/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260355396,"owners_count":22996469,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-17T12:05:32.493Z","updated_at":"2025-07-31T18:33:26.460Z","avatar_url":"https://github.com/danjamk.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matomo AWS Server\nDeploy Matomo web analytics on AWS EC2 with CDK - cost-optimized and production-ready.\n\nThis CDK project provides infrastructure-as-code deployment for a self-hosted Matomo analytics server on AWS. \nBy deploying your own Matomo instance, you gain full data ownership, eliminate sampling limitations, and consolidate \nmultiple marketing tools (heatmaps, A/B testing, attribution) into a single platform. This approach is particularly \nvaluable for Shopify stores requiring custom analytics, first-party data control, and the ability to join visitor \ndata with customer databases for advanced attribution modeling. The deployment includes EC2 instance provisioning, \nRDS MySQL setup, and basic security configurations to get you up and running quickly.\n\nThe following article talks a bit more about the motivations.  \n[Self-Hosted Matomo Web Analytics on AWS: How We Enhanced Our Shopify Analytics Stack and Cut Marketing Tool Costs](https://medium.com/@dan.jam.kuhn/self-hosted-matomo-web-analytics-on-aws-how-we-enhanced-our-shopify-analytics-stack-and-cut-3476526132a8)\n\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![AWS CDK](https://img.shields.io/badge/AWS%20CDK-v2.165.0-orange)](https://aws.amazon.com/cdk/)\n[![Python](https://img.shields.io/badge/Python-3.8%2B-blue)](https://www.python.org/)\n\n## 🚀 Quick Start\n\nDeploy Matomo on AWS in 3 simple steps:\n\n### Option 1: Using Make (Recommended)\n```bash\n# 1. Clone and configure\ngit clone \u003cthis-repo\u003e\ncd matomo-aws-server\n\n# 2. Complete deployment with validation\nmake fresh-deploy\n\n# 3. Access Matomo at the provided URL\n```\n\n### Option 2: Using Scripts Directly\n```bash\n# 1. Clone and configure\ngit clone \u003cthis-repo\u003e\ncd matomo-aws-server\n\n# 2. Run one-time setup\n./scripts/setup.sh\n\n# 3. Deploy to AWS\n./scripts/deploy.sh\n\n# 4. Access Matomo at the provided URL\n```\n\n## 📋 Table of Contents\n\n- [Features](#-features)\n- [Prerequisites](#-prerequisites)\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [Deployment](#-deployment)\n- [Usage](#-usage)\n- [Makefile Commands](#%EF%B8%8F-makefile-commands)\n- [Available Scripts](#%EF%B8%8F-available-scripts)\n- [Security](#-security)\n- [Costs](#-costs)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n\n## ✨ Features\n\n### 🏗️ Infrastructure\n- **Multi-stack CDK architecture** - Separate networking, database, and compute\n- **Cost-optimized deployment** - Single AZ, minimal resources, free tier eligible\n- **RDS MySQL Database** - Managed MySQL database with automatic backups\n- **Secure by default** - Private subnets, security groups, encrypted secrets\n\n### 🔐 Security\n- **SSH keys in Parameter Store** - No local key files to manage\n- **Database credentials in Secrets Manager** - Auto-generated secure passwords\n- **IAM least privilege** - Minimal permissions for all resources\n- **VPC isolation** - Private database subnets, controlled access\n\n### 🛠️ Automation\n- **Two-step deployment** - `./scripts/setup.sh` (once) then `./scripts/deploy.sh` (deploy/test cycles)\n- **Automatic Matomo installation** - Fully configured on first boot\n- **Easy cleanup** - `./scripts/destroy.sh` removes everything\n- **Connection details** - `./scripts/get-info.sh` shows all access info\n- **Cross-platform** - Linux/macOS native, Windows via WSL2\n\n### ⚠️ What This Project Does NOT Include\n\nThis project focuses on core infrastructure deployment. **You will need to configure separately**:\n\n- 🌍 **Domain Name / DNS** - Point your domain to the EC2 instance\n- 🔒 **SSL Certificates** - Set up HTTPS with Let's Encrypt, ACM, or your own certs  \n- 📧 **Email Configuration** - SMTP settings for Matomo notifications\n- 🔄 **Load Balancing** - For high-availability deployments\n- 📊 **Advanced Monitoring** - CloudWatch dashboards, alerting\n- 🔐 **WAF / DDoS Protection** - Additional security layers\n\n**This keeps the project simple and focused** while giving you flexibility to add these components as needed.\n\n## 📋 Prerequisites\n\n### Required Tools\n- **AWS CLI** - [Install Guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)\n- **AWS CDK** - `npm install -g aws-cdk`\n- **Python 3.8+** - [Download](https://www.python.org/downloads/)\n- **Git** - [Install Guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)\n\n### AWS Setup\n```bash\n# Configure AWS credentials\naws configure\n\n# Verify access\naws sts get-caller-identity\n```\n\n### 🪟 Windows Users\n\nThis project uses Bash scripts that don't run natively on Windows. **We recommend using WSL (Windows Subsystem for Linux)** for the best experience:\n\n#### **Option 1: WSL2 (Recommended)**\n```powershell\n# Install WSL2 with Ubuntu (run as Administrator)\nwsl --install\n\n# Restart your computer when prompted\n\n# Access your project files in WSL\nwsl\ncd /mnt/c/path/to/your/project/matomo-aws-server\n\n# Install tools in WSL Ubuntu environment\nsudo apt update\nsudo apt install python3 python3-pip nodejs npm git\n\n# Install AWS CLI\ncurl \"https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip\" -o \"awscliv2.zip\"\nunzip awscliv2.zip\nsudo ./aws/install\n\n# Install CDK\nsudo npm install -g aws-cdk\n\n# Configure AWS (your Windows AWS credentials work in WSL)\naws configure\n\n# Use project normally\n./scripts/deploy.sh\n```\n\n#### **Option 2: Manual Deployment (PowerShell)**\nIf you prefer not to use WSL, you can deploy manually:\n```powershell\n# Install Python, Node.js, AWS CLI, and CDK on Windows first\n# Then in PowerShell:\n\npython -m venv venv\nvenv\\Scripts\\activate\npip install -r requirements.txt\n\n# Deploy manually\ncdk bootstrap\ncdk deploy --all\n\n# Get deployment info\naws cloudformation describe-stacks --stack-name matomo-analytics-compute --query \"Stacks[0].Outputs\"\n```\n\n#### **WSL Benefits:**\n- ✅ All scripts work exactly as documented\n- ✅ No modifications needed\n- ✅ Same experience as macOS/Linux\n- ✅ Full compatibility with project instructions\n\n### 🐧 Linux Users\n\n**Excellent news!** This project has **native Linux support** with no modifications needed. Linux compatibility is actually better than macOS since most tools are designed for Linux first.\n\n#### **Ubuntu/Debian Setup:**\n```bash\n# Install required tools\nsudo apt update\nsudo apt install python3 python3-pip python3-venv nodejs npm git curl unzip\n\n# Install AWS CLI\ncurl \"https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip\" -o \"awscliv2.zip\"\nunzip awscliv2.zip \u0026\u0026 sudo ./aws/install\n\n# Install CDK\nsudo npm install -g aws-cdk\n\n# Configure AWS and deploy\naws configure\n./scripts/deploy.sh\n```\n\n#### **RHEL/CentOS/Fedora:**\n```bash\n# Replace 'apt' with 'dnf' (or 'yum' for older versions)\nsudo dnf install python3 python3-pip nodejs npm git curl unzip\n# Then follow AWS CLI and CDK installation above\n```\n\n#### **Linux Advantages:**\n- ✅ **Native Bash support** - All scripts work perfectly\n- ✅ **Package managers** - Easy dependency installation  \n- ✅ **No compatibility issues** - Everything runs natively\n- ✅ **Container-ready** - Perfect for CI/CD pipelines\n\n### Permissions Required\nYour AWS user/role needs these permissions:\n- CloudFormation (full access)\n- EC2 (full access)\n- VPC (full access)\n- IAM (create/manage roles)\n- RDS (if using database)\n- Secrets Manager (if using database)\n- Systems Manager Parameter Store\n\n## 🏗️ Architecture\n\n### Infrastructure Components\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    AWS Region                          │\n│  ┌─────────────────────────────────────────────────────┐ │\n│  │                     VPC                            │ │\n│  │  ┌─────────────┐    ┌──────────────────────────────┐ │ │\n│  │  │   Public    │    │         Private              │ │ │\n│  │  │   Subnet    │    │        Subnet                │ │ │\n│  │  │             │    │                              │ │ │\n│  │  │ ┌─────────┐ │    │  ┌─────────────────────────┐ │ │ │\n│  │  │ │   EC2   │ │    │  │      RDS MySQL          │ │ │ │\n│  │  │ │ Matomo  │ │    │  │    (Optional)           │ │ │ │\n│  │  │ │ Server  │ │    │  │                         │ │ │ │\n│  │  │ └─────────┘ │    │  └─────────────────────────┘ │ │ │\n│  │  └─────────────┘    └──────────────────────────────┘ │ │\n│  └─────────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────┘\n```\n\n### Stack Organization\n1. **NetworkingStack** - VPC, subnets, security groups, NAT gateway\n2. **DatabaseStack** - RDS MySQL, subnet group, secrets (optional)\n3. **ComputeStack** - EC2 instance, IAM roles, user data script\n\n### Cost Optimization\n- **Single AZ deployment** - Reduces cross-AZ charges\n- **t3.micro instances** - Free tier eligible\n- **Minimal storage** - 20GB RDS, 8GB EC2\n- **Single NAT Gateway** - Shared across subnets\n- **No backups by default** - Reduces RDS costs\n\n## ⚙️ Configuration\n\nConfiguration is managed via `cdk.json` context:\n\n### Basic Configuration\n```json\n{\n  \"context\": {\n    \"matomo\": {\n      \"projectName\": \"matomo-analytics\",\n      \"enableDatabase\": false,\n      \"costOptimized\": true,\n      \"instanceType\": \"t3.micro\",\n      \"allowedSshCidr\": \"0.0.0.0/0\"\n    }\n  }\n}\n```\n\n### Database Configuration\n```json\n{\n  \"context\": {\n    \"matomo\": {\n      \"enableDatabase\": true,\n      \"databaseConfig\": {\n        \"instanceClass\": \"db.t3.micro\",\n        \"allocatedStorage\": 20,\n        \"multiAZ\": false,\n        \"backupRetention\": 0\n      }\n    }\n  }\n}\n```\n\n### Network Configuration\n```json\n{\n  \"context\": {\n    \"matomo\": {\n      \"networking\": {\n        \"singleNatGateway\": true,\n        \"enableVpcEndpoints\": false,\n        \"vpcCidr\": \"10.0.0.0/16\"\n      }\n    }\n  }\n}\n```\n\n### Configuration Options\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `projectName` | `matomo-analytics` | Prefix for all AWS resources |\n| `enableDatabase` | `false` | Deploy RDS MySQL instance |\n| `costOptimized` | `true` | Use single AZ, minimal resources |\n| `instanceType` | `t3.micro` | EC2 instance type |\n| `allowedSshCidr` | `0.0.0.0/0` | IP range allowed SSH access |\n\n## 🚀 Deployment\n\n### Method 1: Using Makefile (Recommended)\n```bash\n# Clone the repository\ngit clone \u003cthis-repo\u003e\ncd matomo-aws-server\n\n# Complete deployment with validation\nmake fresh-deploy\n```\n\n**Makefile Benefits:**\n- **Single command deployment** - Everything automated\n- **Built-in validation** - Automatic post-deployment checks\n- **Better error handling** - Intelligent retry and wait logic\n- **Convenient workflows** - Common tasks simplified\n\n### Method 2: Using Scripts Directly\n```bash\n# Clone the repository\ngit clone \u003cthis-repo\u003e\ncd matomo-aws-server\n\n# Step 1: One-time setup (prerequisites, dependencies, CDK bootstrap)\n./scripts/setup.sh\n\n# Step 2: Deploy to AWS (repeat for updates)\n./scripts/deploy.sh\n```\n\n**Two-Script Design Benefits:**\n- **Faster iterations** - Skip setup after initial run\n- **Clear workflow** - Setup once, deploy repeatedly\n- **Better debugging** - Separate setup vs deployment issues\n\n#### Setup Script (`./scripts/setup.sh`) handles:\n- ✅ Check prerequisites (AWS CLI, CDK, Python)\n- ✅ Verify AWS credentials\n- ✅ Create virtual environment \u0026 install dependencies\n- ✅ Bootstrap CDK (one-time AWS setup)\n\n#### Deploy Script (`./scripts/deploy.sh`) handles:\n- ✅ Deploy all CDK stacks\n- ✅ Display connection information\n\n### Method 3: Manual Deployment\n```bash\n# Install dependencies\npython3 -m venv venv\nsource venv/bin/activate\npip install -r requirements.txt\n\n# Bootstrap CDK (first time only)\ncdk bootstrap\n\n# Deploy all stacks\ncdk deploy --all\n```\n\n### Deployment Options\n\n#### Deploy with Database\n```bash\n# Edit cdk.json to enable database\nsed -i '' 's/\"enableDatabase\": false/\"enableDatabase\": true/' cdk.json\n\n# Setup (if not done already)\n./scripts/setup.sh\n\n# Deploy\n./scripts/deploy.sh\n```\n\n#### Deploy Specific Stacks\n```bash\n# Deploy only networking\ncdk deploy matomo-analytics-networking\n\n# Deploy networking and compute (no database)\ncdk deploy matomo-analytics-networking matomo-analytics-compute\n```\n\n## 📖 Usage\n\n### Accessing Matomo\n\nAfter deployment, you'll receive:\n- 🌐 **Matomo URL**: `http://YOUR-EC2-IP`\n- 🔐 **SSH Access**: Command to connect to the server\n- 🗄️ **Database Info**: Connection details (if RDS enabled)\n\n### Getting Connection Information\n```bash\n# View all deployment details\n./scripts/get-info.sh\n\n# Get database password specifically\n./scripts/get-db-password.sh\n\n# Get just the SSH command\ncdk outputs | grep SshCommand\n```\n\n### SSH Access\n```bash\n# The get-info script automatically retrieves your SSH key\n./scripts/get-info.sh\n\n# Then connect using the provided command\nssh -i matomo-key.pem ec2-user@YOUR-EC2-IP\n```\n\n### Database Credentials\nWhen RDS MySQL is enabled, database credentials are automatically generated and stored securely:\n\n```bash\n# Get database username and password\n./scripts/get-db-password.sh\n\n# Alternative: Manual retrieval using AWS CLI\nSECRET_ARN=$(aws cloudformation describe-stacks --stack-name matomo-analytics-database --query \"Stacks[0].Outputs[?OutputKey=='DatabaseSecretArn'].OutputValue\" --output text)\naws secretsmanager get-secret-value --secret-id $SECRET_ARN --query 'SecretString' --output text | python -c \"import sys, json; data=json.load(sys.stdin); print(f'Username: {data[\\\"username\\\"]}'); print(f'Password: {data[\\\"password\\\"]}')\"\n```\n\n### Matomo Setup\n\n1. **Access the web interface** at the provided URL\n2. **Complete the installation wizard**:\n   - Database: Use provided RDS MySQL connection details\n   - Admin user: Create your admin account\n   - Website: Add your first website to track\n3. **Install the tracking code** on your website\n\n### ⚠️ Important: DNS and SSL Setup Required\n\n**This project deploys Matomo with HTTP only** and provides a public IP address. For production use, you'll need to configure:\n\n#### 🌍 Domain Name Setup\n1. **Point your domain** to the EC2 instance public IP:\n   ```bash\n   # Example DNS A record\n   analytics.yourdomain.com → YOUR-EC2-PUBLIC-IP\n   ```\n\n2. **Update Matomo trusted hosts** in `/var/www/html/config/config.ini.php`:\n   ```ini\n   [General]\n   trusted_hosts[] = \"analytics.yourdomain.com\"\n   ```\n\n#### 🔒 SSL Certificate Setup\n1. **Install Let's Encrypt** (recommended for free SSL):\n   ```bash\n   sudo dnf install certbot python3-certbot-apache\n   sudo certbot --apache -d analytics.yourdomain.com\n   ```\n\n2. **Or use AWS Certificate Manager** with Application Load Balancer\n3. **Or bring your own certificate** and configure Apache SSL\n\n#### 🛡️ Security Considerations\n- **Never use HTTP in production** - Always configure SSL/TLS\n- **Update trusted hosts** to prevent HTTP Host header attacks\n- **Consider AWS WAF** for additional protection\n- **Set up monitoring** and backup strategies\n\n### Post-Deployment Validation\n\nAfter deployment, use the validation scripts to ensure everything is working correctly:\n\n```bash\n# 1. Validate AWS infrastructure\n./scripts/validate-infrastructure.sh\n\n# 2. Validate Matomo installation (single check)\n./scripts/validate-matomo.sh\n\n# 3. Wait for Matomo installation to complete (for fresh deployments)\n./scripts/validate-matomo.sh --wait\n\n```\n\n#### Validation Features\n\n**Infrastructure Validation (`validate-infrastructure.sh`)**:\n- ✅ Verifies VPC, subnets, and security groups\n- ✅ Checks EC2 instance status and configuration\n- ✅ Validates RDS instance status and AWS resources (if enabled)\n- ✅ Tests security group rules and access restrictions\n- ✅ Validates database credentials in Secrets Manager\n- ℹ️ **Note**: Database is in private subnets (not publicly accessible - this is correct)\n\n**Matomo Installation Validation (`validate-matomo.sh`)**:\n- ✅ Tests HTTP connectivity to Matomo URL\n- ✅ Validates web interface response and content\n- ✅ Detects installation wizard vs. completed setup\n- ✅ Checks SSL/HTTPS configuration\n- ✅ **Wait mode**: Monitors installation progress with intelligent retry\n- ✅ **Timeout control**: Configurable wait time (default: 15 minutes)\n\n```bash\n# Basic validation (single check)\n./scripts/validate-matomo.sh\n\n# Wait for installation to complete\n./scripts/validate-matomo.sh --wait\n\n# Custom timeout (30 minutes)\n./scripts/validate-matomo.sh --wait --timeout 1800\n\n# Custom retry interval (60 seconds)\n./scripts/validate-matomo.sh --wait --interval 60\n```\n\n\n### Manual Installation Monitoring\n```bash\n# SSH into the server and check logs\nssh -i matomo-key.pem ec2-user@YOUR-EC2-IP\n\n# View installation logs\nsudo tail -f /var/log/matomo-install.log\n\n# Check installation status\ncat /var/www/html/INSTALLATION_STATUS\n```\n\n## 🔐 Security\n\nThis deployment follows AWS security best practices:\n\n### Credentials Management\n- **SSH Keys**: Stored in AWS Systems Manager Parameter Store (encrypted)\n- **Database Passwords**: Auto-generated and stored in AWS Secrets Manager\n- **No Local Secrets**: All sensitive data managed by AWS services\n\n### Network Security\n- **Private Database**: RDS deployed in private subnets only\n- **Security Groups**: Minimal required access (HTTP, HTTPS, SSH)\n- **VPC Isolation**: Complete network isolation from other AWS resources\n\n### Access Control\n- **IAM Roles**: Least privilege access for EC2 instance\n- **SSH Access**: Configurable IP ranges (default allows all - change this!)\n- **Database Access**: Only from EC2 security group\n\n### Security Recommendations\n- [ ] Restrict SSH access to your IP: Update `allowedSshCidr` in `cdk.json`\n- [ ] Enable database backups: Set `backupRetention \u003e 0` for production\n- [ ] Configure Matomo trusted hosts: Edit `/var/www/html/config/config.ini.php`\n- [ ] Set up SSL/TLS: Use ALB with ACM certificate (not included)\n\nFor detailed security information, see [SECURITY.md](docs/SECURITY.md).\n\n## 💰 Costs\n\n### Cost Breakdown (Monthly, US-East-1)\n\n| Component | Free Tier | Paid |\n|-----------|-----------|------|\n| EC2 t3.micro | $0 | $7.50 |\n| RDS db.t3.micro | $0 | $12.50 |\n| EBS Storage (28GB) | $0 | $2.80 |\n| NAT Gateway | N/A | $32.00 |\n| Data Transfer | 1GB free | $0.09/GB |\n\n**Total Monthly Cost:**\n- **With Free Tier**: ~$32 (NAT Gateway only) + $12-15 (RDS) = ~$45-50\n- **Without Free Tier**: ~$55\n\n### Cost Optimization Tips\n- **Use existing VPC**: Skip NAT Gateway if you have one\n- **Optimize database**: Use smaller RDS instances for development\n- **Stop when not needed**: Stop EC2 instance to save compute costs\n- **Use Spot Instances**: Modify the code for 60-90% savings\n\nFor detailed cost information, see [COSTS.md](docs/COSTS.md).\n\n## 🛠️ Makefile Commands\n\nThis project includes a comprehensive Makefile that wraps all scripts with convenient commands:\n\n### Quick Reference\n\n```bash\n# Get help and see all available commands\nmake help\n\n# Common workflows\nmake fresh-deploy          # Complete first-time deployment\nmake quick-deploy           # Quick deployment (setup already done)\nmake redeploy              # Redeploy after changes\nmake check                 # Validate everything is working\n\n# Information and status\nmake info                  # Get deployment details\nmake status                # Alias for info\nmake password              # Get database credentials\n\n# Validation\nmake validate              # Run all validation checks\nmake validate-all          # Run all validation with wait mode\nmake validate-matomo-wait  # Wait for Matomo installation\n\n# Cleanup\nmake clean                 # Interactive cleanup\nmake clean-force           # Automated cleanup (no prompts)\n\n# Advanced\nmake ssh                   # Connect to EC2 instance\nmake logs                  # View installation logs\nmake open                  # Open Matomo in browser\nmake diff                  # Preview changes\n```\n\n### Available Commands\n\n| Command | Description |\n|---------|-------------|\n| `make help` | Show all available commands with descriptions |\n| `make setup` | Run one-time setup (prerequisites, dependencies, CDK bootstrap) |\n| `make deploy` | Deploy Matomo infrastructure to AWS |\n| `make info` | Get all deployment information (IP, SSH, database details) |\n| `make password` | Get database username and password |\n| `make validate-infrastructure` | Validate AWS infrastructure |\n| `make validate-matomo` | Validate Matomo installation (single check) |\n| `make validate-matomo-wait` | Wait for Matomo installation to complete |\n| `make validate` | Run all validation checks |\n| `make validate-all` | Run all validation checks with wait mode |\n| `make clean` | Remove all AWS resources (interactive) |\n| `make clean-force` | Remove all AWS resources (no prompts) |\n| `make ssh` | Connect to EC2 instance via SSH |\n| `make logs` | View Matomo installation logs |\n| `make open` | Open Matomo URL in browser |\n| `make diff` | Preview deployment changes |\n| `make version` | Show tool versions and AWS account info |\n\n### Workflow Examples\n\n```bash\n# First-time deployment\nmake fresh-deploy\n\n# Daily development workflow\nmake diff                  # Preview changes\nmake redeploy             # Deploy changes\nmake check                # Verify everything works\n\n# Troubleshooting\nmake validate-infrastructure  # Check AWS resources\nmake validate-matomo-wait    # Wait for installation\nmake logs                    # View installation logs\nmake ssh                     # Connect to debug\n\n# Cleanup\nmake clean                # Interactive cleanup\nmake clean-force          # For CI/CD automation\n```\n\n## 🛠️ Available Scripts\n\nFor users who prefer direct script usage, this project includes several utility scripts:\n\n| Script | Purpose | Usage |\n|--------|---------|--------|\n| `./scripts/setup.sh` | **Setup** - One-time setup (prerequisites, dependencies, CDK bootstrap) | `./scripts/setup.sh` |\n| `./scripts/deploy.sh` | **Deploy** - Deploy stacks to AWS | `./scripts/deploy.sh` |\n| `./scripts/get-info.sh` | **Info** - Get all deployment details | `./scripts/get-info.sh` |\n| `./scripts/get-db-password.sh` | **Password** - Get database credentials | `./scripts/get-db-password.sh` |\n| `./scripts/validate-infrastructure.sh` | **Validate** - Verify AWS infrastructure | `./scripts/validate-infrastructure.sh` |\n| `./scripts/validate-matomo.sh` | **Validate** - Check Matomo installation | `./scripts/validate-matomo.sh [--wait]` |\n| `./scripts/destroy.sh` | **Destroy** - Remove all AWS resources | `./scripts/destroy.sh [--force]` |\n\n### Script Details\n\n```bash\n# 🛠️ One-time setup (run first)\n./scripts/setup.sh\n\n# 🚀 Deploy to AWS (after setup)\n./scripts/deploy.sh\n\n# 📊 View all deployment information\n./scripts/get-info.sh\n\n# 🔐 Get database username and password\n./scripts/get-db-password.sh\n\n# ✅ Validate infrastructure (VPC, security groups, EC2, RDS)\n./scripts/validate-infrastructure.sh\n\n# ✅ Validate Matomo installation (web interface)\n./scripts/validate-matomo.sh\n\n# ✅ Wait for Matomo installation to complete (with timeout)\n./scripts/validate-matomo.sh --wait --timeout 1800\n\n\n# 🧹 Complete cleanup with confirmation\n./scripts/destroy.sh\n\n# 🧹 Force cleanup without prompts (for automation)\n./scripts/destroy.sh --force\n```\n\n## 🧹 Cleanup\n\n### Complete Cleanup\n\n```bash\n# Interactive cleanup (with confirmation)\n./scripts/destroy.sh\n\n# Force cleanup without prompts (for automation)\n./scripts/destroy.sh --force\n```\n\n#### Cleanup Options\n\n**Interactive Mode (Default)**:\n- Shows detailed deletion plan\n- Requires typing \"DELETE\" to confirm\n- 5-second countdown before proceeding\n- Safe for manual use\n\n**Force Mode (`--force` or `-f`)**:\n- Shows deletion plan but skips confirmation\n- No prompts or countdowns\n- Perfect for automation/CI-CD\n- Use with caution!\n\n```bash\n# Examples\n./scripts/destroy.sh                    # Interactive confirmation\n./scripts/destroy.sh --force            # Skip all prompts  \n./scripts/destroy.sh -f                 # Short form\n./scripts/destroy.sh --help             # Show usage\n```\n\nBoth modes will:\n- ⚠️ **Permanently delete** all AWS resources\n- ⚠️ **Delete all data** (Matomo database, analytics data)\n- ✅ Stop all ongoing charges\n- ✅ Clean up local files\n\n### Partial Cleanup\n```bash\n# Remove only specific stacks\ncdk destroy matomo-analytics-compute\ncdk destroy matomo-analytics-database\ncdk destroy matomo-analytics-networking\n```\n\n## 🛠️ Troubleshooting\n\n### Common Issues\n\n#### Scripts Don't Work on Windows\n```bash\n# Error: './scripts/deploy.sh' is not recognized...\n# Solution: Use WSL2 (recommended)\nwsl --install\nwsl\ncd /mnt/c/path/to/matomo-aws-server\n./scripts/deploy.sh\n\n# Alternative: Deploy manually with PowerShell\npython -m venv venv\nvenv\\Scripts\\activate\ncdk deploy --all\n```\n\n#### Deployment Fails\n```bash\n# Check CDK bootstrap status\ncdk bootstrap --show-template\n\n# Verify AWS credentials\naws sts get-caller-identity\n\n# Check CloudFormation events\naws cloudformation describe-stack-events --stack-name matomo-analytics-networking\n```\n\n#### Can't Access Matomo\n```bash\n# Use validation scripts to diagnose issues\n./scripts/validate-infrastructure.sh     # Check AWS resources\n./scripts/validate-matomo.sh --wait      # Wait for installation\n```\n\n- Wait 10-15 minutes for installation to complete\n- Check security group allows HTTP (port 80)\n- Verify EC2 instance is running\n- Check installation logs on the server\n\n#### SSH Connection Fails\n- Verify SSH key retrieved: `./scripts/get-info.sh`\n- Check security group allows SSH (port 22)\n- Ensure correct IP address and key file permissions\n\nFor more troubleshooting help, see [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).\n\n## 📚 Additional Documentation\n\n- [Security Guide](docs/SECURITY.md) - Detailed security considerations\n- [Cost Optimization](docs/COSTS.md) - Advanced cost optimization strategies  \n- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions\n- [Matomo Analytics Examples](docs/MATOMO_ANALYTICS_EXAMPLES.md) - SQL queries for e-commerce analytics with Matomo\n- [Advanced Analytics Documentation](docs/matomo-advanced-analytics-documentation.md) - Comprehensive guide to advanced Matomo SQL queries\n- [Advanced Analytics SQL File](docs/matomo-advanced-analytics-examples.sql) - Complete SQL query collection\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Matomo](https://matomo.org/) - The open-source web analytics platform\n- [AWS CDK](https://aws.amazon.com/cdk/) - Infrastructure as Code framework\n- Original inspiration from personal client project\n\n---\n\n**Questions?** Open an issue or check the [documentation](docs/) directory.\n\n**Need help?** See [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common solutions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanjamk%2Fmatomo-aws-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdanjamk%2Fmatomo-aws-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdanjamk%2Fmatomo-aws-server/lists"}