Skip to content

danjamk/matomo-aws-server

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

14 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

Matomo AWS Server

Deploy Matomo web analytics on AWS EC2 with CDK - cost-optimized and production-ready.

This CDK project provides infrastructure-as-code deployment for a self-hosted Matomo analytics server on AWS. By deploying your own Matomo instance, you gain full data ownership, eliminate sampling limitations, and consolidate multiple marketing tools (heatmaps, A/B testing, attribution) into a single platform. This approach is particularly valuable for Shopify stores requiring custom analytics, first-party data control, and the ability to join visitor data with customer databases for advanced attribution modeling. The deployment includes EC2 instance provisioning, RDS MySQL setup, and basic security configurations to get you up and running quickly.

The following article talks a bit more about the motivations.
Self-Hosted Matomo Web Analytics on AWS: How We Enhanced Our Shopify Analytics Stack and Cut Marketing Tool Costs

License: MIT AWS CDK Python

πŸš€ Quick Start

Deploy Matomo on AWS in 3 simple steps:

Option 1: Using Make (Recommended)

# 1. Clone and configure
git clone <this-repo>
cd matomo-aws-server

# 2. Complete deployment with validation
make fresh-deploy

# 3. Access Matomo at the provided URL

Option 2: Using Scripts Directly

# 1. Clone and configure
git clone <this-repo>
cd matomo-aws-server

# 2. Run one-time setup
./scripts/setup.sh

# 3. Deploy to AWS
./scripts/deploy.sh

# 4. Access Matomo at the provided URL

πŸ“‹ Table of Contents

✨ Features

πŸ—οΈ Infrastructure

  • Multi-stack CDK architecture - Separate networking, database, and compute
  • Cost-optimized deployment - Single AZ, minimal resources, free tier eligible
  • RDS MySQL Database - Managed MySQL database with automatic backups
  • Secure by default - Private subnets, security groups, encrypted secrets

πŸ” Security

  • SSH keys in Parameter Store - No local key files to manage
  • Database credentials in Secrets Manager - Auto-generated secure passwords
  • IAM least privilege - Minimal permissions for all resources
  • VPC isolation - Private database subnets, controlled access

πŸ› οΈ Automation

  • Two-step deployment - ./scripts/setup.sh (once) then ./scripts/deploy.sh (deploy/test cycles)
  • Automatic Matomo installation - Fully configured on first boot
  • Easy cleanup - ./scripts/destroy.sh removes everything
  • Connection details - ./scripts/get-info.sh shows all access info
  • Cross-platform - Linux/macOS native, Windows via WSL2

⚠️ What This Project Does NOT Include

This project focuses on core infrastructure deployment. You will need to configure separately:

  • 🌍 Domain Name / DNS - Point your domain to the EC2 instance
  • πŸ”’ SSL Certificates - Set up HTTPS with Let's Encrypt, ACM, or your own certs
  • πŸ“§ Email Configuration - SMTP settings for Matomo notifications
  • πŸ”„ Load Balancing - For high-availability deployments
  • πŸ“Š Advanced Monitoring - CloudWatch dashboards, alerting
  • πŸ” WAF / DDoS Protection - Additional security layers

This keeps the project simple and focused while giving you flexibility to add these components as needed.

πŸ“‹ Prerequisites

Required Tools

AWS Setup

# Configure AWS credentials
aws configure

# Verify access
aws sts get-caller-identity

πŸͺŸ Windows Users

This project uses Bash scripts that don't run natively on Windows. We recommend using WSL (Windows Subsystem for Linux) for the best experience:

Option 1: WSL2 (Recommended)

# Install WSL2 with Ubuntu (run as Administrator)
wsl --install

# Restart your computer when prompted

# Access your project files in WSL
wsl
cd /mnt/c/path/to/your/project/matomo-aws-server

# Install tools in WSL Ubuntu environment
sudo apt update
sudo apt install python3 python3-pip nodejs npm git

# Install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

# Install CDK
sudo npm install -g aws-cdk

# Configure AWS (your Windows AWS credentials work in WSL)
aws configure

# Use project normally
./scripts/deploy.sh

Option 2: Manual Deployment (PowerShell)

If you prefer not to use WSL, you can deploy manually:

# Install Python, Node.js, AWS CLI, and CDK on Windows first
# Then in PowerShell:

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

# Deploy manually
cdk bootstrap
cdk deploy --all

# Get deployment info
aws cloudformation describe-stacks --stack-name matomo-analytics-compute --query "Stacks[0].Outputs"

WSL Benefits:

  • βœ… All scripts work exactly as documented
  • βœ… No modifications needed
  • βœ… Same experience as macOS/Linux
  • βœ… Full compatibility with project instructions

🐧 Linux Users

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.

Ubuntu/Debian Setup:

# Install required tools
sudo apt update
sudo apt install python3 python3-pip python3-venv nodejs npm git curl unzip

# Install AWS CLI
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip && sudo ./aws/install

# Install CDK
sudo npm install -g aws-cdk

# Configure AWS and deploy
aws configure
./scripts/deploy.sh

RHEL/CentOS/Fedora:

# Replace 'apt' with 'dnf' (or 'yum' for older versions)
sudo dnf install python3 python3-pip nodejs npm git curl unzip
# Then follow AWS CLI and CDK installation above

Linux Advantages:

  • βœ… Native Bash support - All scripts work perfectly
  • βœ… Package managers - Easy dependency installation
  • βœ… No compatibility issues - Everything runs natively
  • βœ… Container-ready - Perfect for CI/CD pipelines

Permissions Required

Your AWS user/role needs these permissions:

  • CloudFormation (full access)
  • EC2 (full access)
  • VPC (full access)
  • IAM (create/manage roles)
  • RDS (if using database)
  • Secrets Manager (if using database)
  • Systems Manager Parameter Store

πŸ—οΈ Architecture

Infrastructure Components

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                    AWS Region                          β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
β”‚  β”‚                     VPC                            β”‚ β”‚
β”‚  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚
β”‚  β”‚  β”‚   Public    β”‚    β”‚         Private              β”‚ β”‚ β”‚
β”‚  β”‚  β”‚   Subnet    β”‚    β”‚        Subnet                β”‚ β”‚ β”‚
β”‚  β”‚  β”‚             β”‚    β”‚                              β”‚ β”‚ β”‚
β”‚  β”‚  β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚    β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ β”‚ β”‚
β”‚  β”‚  β”‚ β”‚   EC2   β”‚ β”‚    β”‚  β”‚      RDS MySQL          β”‚ β”‚ β”‚ β”‚
β”‚  β”‚  β”‚ β”‚ Matomo  β”‚ β”‚    β”‚  β”‚    (Optional)           β”‚ β”‚ β”‚ β”‚
β”‚  β”‚  β”‚ β”‚ Server  β”‚ β”‚    β”‚  β”‚                         β”‚ β”‚ β”‚ β”‚
β”‚  β”‚  β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚    β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β”‚
β”‚  β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Stack Organization

  1. NetworkingStack - VPC, subnets, security groups, NAT gateway
  2. DatabaseStack - RDS MySQL, subnet group, secrets (optional)
  3. ComputeStack - EC2 instance, IAM roles, user data script

Cost Optimization

  • Single AZ deployment - Reduces cross-AZ charges
  • t3.micro instances - Free tier eligible
  • Minimal storage - 20GB RDS, 8GB EC2
  • Single NAT Gateway - Shared across subnets
  • No backups by default - Reduces RDS costs

βš™οΈ Configuration

Configuration is managed via cdk.json context:

Basic Configuration

{
  "context": {
    "matomo": {
      "projectName": "matomo-analytics",
      "enableDatabase": false,
      "costOptimized": true,
      "instanceType": "t3.micro",
      "allowedSshCidr": "0.0.0.0/0"
    }
  }
}

Database Configuration

{
  "context": {
    "matomo": {
      "enableDatabase": true,
      "databaseConfig": {
        "instanceClass": "db.t3.micro",
        "allocatedStorage": 20,
        "multiAZ": false,
        "backupRetention": 0
      }
    }
  }
}

Network Configuration

{
  "context": {
    "matomo": {
      "networking": {
        "singleNatGateway": true,
        "enableVpcEndpoints": false,
        "vpcCidr": "10.0.0.0/16"
      }
    }
  }
}

Configuration Options

Option Default Description
projectName matomo-analytics Prefix for all AWS resources
enableDatabase false Deploy RDS MySQL instance
costOptimized true Use single AZ, minimal resources
instanceType t3.micro EC2 instance type
allowedSshCidr 0.0.0.0/0 IP range allowed SSH access

πŸš€ Deployment

Method 1: Using Makefile (Recommended)

# Clone the repository
git clone <this-repo>
cd matomo-aws-server

# Complete deployment with validation
make fresh-deploy

Makefile Benefits:

  • Single command deployment - Everything automated
  • Built-in validation - Automatic post-deployment checks
  • Better error handling - Intelligent retry and wait logic
  • Convenient workflows - Common tasks simplified

Method 2: Using Scripts Directly

# Clone the repository
git clone <this-repo>
cd matomo-aws-server

# Step 1: One-time setup (prerequisites, dependencies, CDK bootstrap)
./scripts/setup.sh

# Step 2: Deploy to AWS (repeat for updates)
./scripts/deploy.sh

Two-Script Design Benefits:

  • Faster iterations - Skip setup after initial run
  • Clear workflow - Setup once, deploy repeatedly
  • Better debugging - Separate setup vs deployment issues

Setup Script (./scripts/setup.sh) handles:

  • βœ… Check prerequisites (AWS CLI, CDK, Python)
  • βœ… Verify AWS credentials
  • βœ… Create virtual environment & install dependencies
  • βœ… Bootstrap CDK (one-time AWS setup)

Deploy Script (./scripts/deploy.sh) handles:

  • βœ… Deploy all CDK stacks
  • βœ… Display connection information

Method 3: Manual Deployment

# Install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Bootstrap CDK (first time only)
cdk bootstrap

# Deploy all stacks
cdk deploy --all

Deployment Options

Deploy with Database

# Edit cdk.json to enable database
sed -i '' 's/"enableDatabase": false/"enableDatabase": true/' cdk.json

# Setup (if not done already)
./scripts/setup.sh

# Deploy
./scripts/deploy.sh

Deploy Specific Stacks

# Deploy only networking
cdk deploy matomo-analytics-networking

# Deploy networking and compute (no database)
cdk deploy matomo-analytics-networking matomo-analytics-compute

πŸ“– Usage

Accessing Matomo

After deployment, you'll receive:

  • 🌐 Matomo URL: http://YOUR-EC2-IP
  • πŸ” SSH Access: Command to connect to the server
  • πŸ—„οΈ Database Info: Connection details (if RDS enabled)

Getting Connection Information

# View all deployment details
./scripts/get-info.sh

# Get database password specifically
./scripts/get-db-password.sh

# Get just the SSH command
cdk outputs | grep SshCommand

SSH Access

# The get-info script automatically retrieves your SSH key
./scripts/get-info.sh

# Then connect using the provided command
ssh -i matomo-key.pem ec2-user@YOUR-EC2-IP

Database Credentials

When RDS MySQL is enabled, database credentials are automatically generated and stored securely:

# Get database username and password
./scripts/get-db-password.sh

# Alternative: Manual retrieval using AWS CLI
SECRET_ARN=$(aws cloudformation describe-stacks --stack-name matomo-analytics-database --query "Stacks[0].Outputs[?OutputKey=='DatabaseSecretArn'].OutputValue" --output text)
aws 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\"]}')"

Matomo Setup

  1. Access the web interface at the provided URL
  2. Complete the installation wizard:
    • Database: Use provided RDS MySQL connection details
    • Admin user: Create your admin account
    • Website: Add your first website to track
  3. Install the tracking code on your website

⚠️ Important: DNS and SSL Setup Required

This project deploys Matomo with HTTP only and provides a public IP address. For production use, you'll need to configure:

🌍 Domain Name Setup

  1. Point your domain to the EC2 instance public IP:

    # Example DNS A record
    analytics.yourdomain.com β†’ YOUR-EC2-PUBLIC-IP
  2. Update Matomo trusted hosts in /var/www/html/config/config.ini.php:

    [General]
    trusted_hosts[] = "analytics.yourdomain.com"

πŸ”’ SSL Certificate Setup

  1. Install Let's Encrypt (recommended for free SSL):

    sudo dnf install certbot python3-certbot-apache
    sudo certbot --apache -d analytics.yourdomain.com
  2. Or use AWS Certificate Manager with Application Load Balancer

  3. Or bring your own certificate and configure Apache SSL

πŸ›‘οΈ Security Considerations

  • Never use HTTP in production - Always configure SSL/TLS
  • Update trusted hosts to prevent HTTP Host header attacks
  • Consider AWS WAF for additional protection
  • Set up monitoring and backup strategies

Post-Deployment Validation

After deployment, use the validation scripts to ensure everything is working correctly:

# 1. Validate AWS infrastructure
./scripts/validate-infrastructure.sh

# 2. Validate Matomo installation (single check)
./scripts/validate-matomo.sh

# 3. Wait for Matomo installation to complete (for fresh deployments)
./scripts/validate-matomo.sh --wait

Validation Features

Infrastructure Validation (validate-infrastructure.sh):

  • βœ… Verifies VPC, subnets, and security groups
  • βœ… Checks EC2 instance status and configuration
  • βœ… Validates RDS instance status and AWS resources (if enabled)
  • βœ… Tests security group rules and access restrictions
  • βœ… Validates database credentials in Secrets Manager
  • ℹ️ Note: Database is in private subnets (not publicly accessible - this is correct)

Matomo Installation Validation (validate-matomo.sh):

  • βœ… Tests HTTP connectivity to Matomo URL
  • βœ… Validates web interface response and content
  • βœ… Detects installation wizard vs. completed setup
  • βœ… Checks SSL/HTTPS configuration
  • βœ… Wait mode: Monitors installation progress with intelligent retry
  • βœ… Timeout control: Configurable wait time (default: 15 minutes)
# Basic validation (single check)
./scripts/validate-matomo.sh

# Wait for installation to complete
./scripts/validate-matomo.sh --wait

# Custom timeout (30 minutes)
./scripts/validate-matomo.sh --wait --timeout 1800

# Custom retry interval (60 seconds)
./scripts/validate-matomo.sh --wait --interval 60

Manual Installation Monitoring

# SSH into the server and check logs
ssh -i matomo-key.pem ec2-user@YOUR-EC2-IP

# View installation logs
sudo tail -f /var/log/matomo-install.log

# Check installation status
cat /var/www/html/INSTALLATION_STATUS

πŸ” Security

This deployment follows AWS security best practices:

Credentials Management

  • SSH Keys: Stored in AWS Systems Manager Parameter Store (encrypted)
  • Database Passwords: Auto-generated and stored in AWS Secrets Manager
  • No Local Secrets: All sensitive data managed by AWS services

Network Security

  • Private Database: RDS deployed in private subnets only
  • Security Groups: Minimal required access (HTTP, HTTPS, SSH)
  • VPC Isolation: Complete network isolation from other AWS resources

Access Control

  • IAM Roles: Least privilege access for EC2 instance
  • SSH Access: Configurable IP ranges (default allows all - change this!)
  • Database Access: Only from EC2 security group

Security Recommendations

  • Restrict SSH access to your IP: Update allowedSshCidr in cdk.json
  • Enable database backups: Set backupRetention > 0 for production
  • Configure Matomo trusted hosts: Edit /var/www/html/config/config.ini.php
  • Set up SSL/TLS: Use ALB with ACM certificate (not included)

For detailed security information, see SECURITY.md.

πŸ’° Costs

Cost Breakdown (Monthly, US-East-1)

Component Free Tier Paid
EC2 t3.micro $0 $7.50
RDS db.t3.micro $0 $12.50
EBS Storage (28GB) $0 $2.80
NAT Gateway N/A $32.00
Data Transfer 1GB free $0.09/GB

Total Monthly Cost:

  • With Free Tier: ~$32 (NAT Gateway only) + $12-15 (RDS) = ~$45-50
  • Without Free Tier: ~$55

Cost Optimization Tips

  • Use existing VPC: Skip NAT Gateway if you have one
  • Optimize database: Use smaller RDS instances for development
  • Stop when not needed: Stop EC2 instance to save compute costs
  • Use Spot Instances: Modify the code for 60-90% savings

For detailed cost information, see COSTS.md.

πŸ› οΈ Makefile Commands

This project includes a comprehensive Makefile that wraps all scripts with convenient commands:

Quick Reference

# Get help and see all available commands
make help

# Common workflows
make fresh-deploy          # Complete first-time deployment
make quick-deploy           # Quick deployment (setup already done)
make redeploy              # Redeploy after changes
make check                 # Validate everything is working

# Information and status
make info                  # Get deployment details
make status                # Alias for info
make password              # Get database credentials

# Validation
make validate              # Run all validation checks
make validate-all          # Run all validation with wait mode
make validate-matomo-wait  # Wait for Matomo installation

# Cleanup
make clean                 # Interactive cleanup
make clean-force           # Automated cleanup (no prompts)

# Advanced
make ssh                   # Connect to EC2 instance
make logs                  # View installation logs
make open                  # Open Matomo in browser
make diff                  # Preview changes

Available Commands

Command Description
make help Show all available commands with descriptions
make setup Run one-time setup (prerequisites, dependencies, CDK bootstrap)
make deploy Deploy Matomo infrastructure to AWS
make info Get all deployment information (IP, SSH, database details)
make password Get database username and password
make validate-infrastructure Validate AWS infrastructure
make validate-matomo Validate Matomo installation (single check)
make validate-matomo-wait Wait for Matomo installation to complete
make validate Run all validation checks
make validate-all Run all validation checks with wait mode
make clean Remove all AWS resources (interactive)
make clean-force Remove all AWS resources (no prompts)
make ssh Connect to EC2 instance via SSH
make logs View Matomo installation logs
make open Open Matomo URL in browser
make diff Preview deployment changes
make version Show tool versions and AWS account info

Workflow Examples

# First-time deployment
make fresh-deploy

# Daily development workflow
make diff                  # Preview changes
make redeploy             # Deploy changes
make check                # Verify everything works

# Troubleshooting
make validate-infrastructure  # Check AWS resources
make validate-matomo-wait    # Wait for installation
make logs                    # View installation logs
make ssh                     # Connect to debug

# Cleanup
make clean                # Interactive cleanup
make clean-force          # For CI/CD automation

πŸ› οΈ Available Scripts

For users who prefer direct script usage, this project includes several utility scripts:

Script Purpose Usage
./scripts/setup.sh Setup - One-time setup (prerequisites, dependencies, CDK bootstrap) ./scripts/setup.sh
./scripts/deploy.sh Deploy - Deploy stacks to AWS ./scripts/deploy.sh
./scripts/get-info.sh Info - Get all deployment details ./scripts/get-info.sh
./scripts/get-db-password.sh Password - Get database credentials ./scripts/get-db-password.sh
./scripts/validate-infrastructure.sh Validate - Verify AWS infrastructure ./scripts/validate-infrastructure.sh
./scripts/validate-matomo.sh Validate - Check Matomo installation ./scripts/validate-matomo.sh [--wait]
./scripts/destroy.sh Destroy - Remove all AWS resources ./scripts/destroy.sh [--force]

Script Details

# πŸ› οΈ One-time setup (run first)
./scripts/setup.sh

# πŸš€ Deploy to AWS (after setup)
./scripts/deploy.sh

# πŸ“Š View all deployment information
./scripts/get-info.sh

# πŸ” Get database username and password
./scripts/get-db-password.sh

# βœ… Validate infrastructure (VPC, security groups, EC2, RDS)
./scripts/validate-infrastructure.sh

# βœ… Validate Matomo installation (web interface)
./scripts/validate-matomo.sh

# βœ… Wait for Matomo installation to complete (with timeout)
./scripts/validate-matomo.sh --wait --timeout 1800


# 🧹 Complete cleanup with confirmation
./scripts/destroy.sh

# 🧹 Force cleanup without prompts (for automation)
./scripts/destroy.sh --force

🧹 Cleanup

Complete Cleanup

# Interactive cleanup (with confirmation)
./scripts/destroy.sh

# Force cleanup without prompts (for automation)
./scripts/destroy.sh --force

Cleanup Options

Interactive Mode (Default):

  • Shows detailed deletion plan
  • Requires typing "DELETE" to confirm
  • 5-second countdown before proceeding
  • Safe for manual use

Force Mode (--force or -f):

  • Shows deletion plan but skips confirmation
  • No prompts or countdowns
  • Perfect for automation/CI-CD
  • Use with caution!
# Examples
./scripts/destroy.sh                    # Interactive confirmation
./scripts/destroy.sh --force            # Skip all prompts  
./scripts/destroy.sh -f                 # Short form
./scripts/destroy.sh --help             # Show usage

Both modes will:

  • ⚠️ Permanently delete all AWS resources
  • ⚠️ Delete all data (Matomo database, analytics data)
  • βœ… Stop all ongoing charges
  • βœ… Clean up local files

Partial Cleanup

# Remove only specific stacks
cdk destroy matomo-analytics-compute
cdk destroy matomo-analytics-database
cdk destroy matomo-analytics-networking

πŸ› οΈ Troubleshooting

Common Issues

Scripts Don't Work on Windows

# Error: './scripts/deploy.sh' is not recognized...
# Solution: Use WSL2 (recommended)
wsl --install
wsl
cd /mnt/c/path/to/matomo-aws-server
./scripts/deploy.sh

# Alternative: Deploy manually with PowerShell
python -m venv venv
venv\Scripts\activate
cdk deploy --all

Deployment Fails

# Check CDK bootstrap status
cdk bootstrap --show-template

# Verify AWS credentials
aws sts get-caller-identity

# Check CloudFormation events
aws cloudformation describe-stack-events --stack-name matomo-analytics-networking

Can't Access Matomo

# Use validation scripts to diagnose issues
./scripts/validate-infrastructure.sh     # Check AWS resources
./scripts/validate-matomo.sh --wait      # Wait for installation
  • Wait 10-15 minutes for installation to complete
  • Check security group allows HTTP (port 80)
  • Verify EC2 instance is running
  • Check installation logs on the server

SSH Connection Fails

  • Verify SSH key retrieved: ./scripts/get-info.sh
  • Check security group allows SSH (port 22)
  • Ensure correct IP address and key file permissions

For more troubleshooting help, see TROUBLESHOOTING.md.

πŸ“š Additional Documentation

🀝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Commit your changes: git commit -m 'Add amazing feature'
  4. Push to the branch: git push origin feature/amazing-feature
  5. Open a Pull Request

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ™ Acknowledgments

  • Matomo - The open-source web analytics platform
  • AWS CDK - Infrastructure as Code framework
  • Original inspiration from personal client project

Questions? Open an issue or check the documentation directory.

Need help? See TROUBLESHOOTING.md for common solutions.

About

This project deploys an AWS EC2 server with Matomo web analytics server

Resources

License

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 2

  •  
  •