# 13: Matomo - Web Analytics

Matomo (formerly Piwik) is a full‑featured, self‑hosted web analytics platform. This guide covers installation and runtime specifics when deploying via Infinity Tools. For comprehensive configuration and administration, see the [official Matomo documentation](https://matomo.org/docs/).

## Architecture Overview

- ✅ **Services:** Matomo (PHP/Apache) + MariaDB 10.11
- ✅ **Reverse Proxy:** Traefik with Let's Encrypt (recommended) or standalone
- ✅ **Networking:** Traefik proxy network + `borgmatic-db` for DB backups
- ✅ **Data:** App config/logs + database volume

## Prerequisites

- ✅ **Traefik installed** (Chapter 4)
- ✅ **Docker installed** (Chapter 3)
- ✅ **Apprise installed** (Chapter 5) for notifications
- ✅ **Borgmatic installed** (Chapter 6) for automated backups
- ✅ **Domain configured** (Chapter 4.5) for HTTPS

**Interdependencies:** MariaDB joins `borgmatic-db` for backup discovery. Borgmatic relies on Apprise for notifications.

## Installation Methods

### Via Infinity Tools Menu

```
📱 APPLICATIONS → Matomo → Install
```

### Command Line

```
# Status (no changes)
sudo bash /opt/InfinityTools/Solutions/setup-matomo.sh --status

# Interactive installation
sudo bash /opt/InfinityTools/Solutions/setup-matomo.sh --install
```

## Key Configuration

- **SSL Mode:** Traefik (HTTPS) or standalone (HTTP or self‑signed HTTPS)
- **Domain:** Required for Traefik (e.g., `analytics.example.com`)
- **Standalone Port:** Required if not using Traefik
- **Database:** MariaDB 10.11 with tuned params

## Generated Files & Directories

- `/opt/speedbits/matomo/.env` — Installation parameters and DB creds
- `/opt/speedbits/matomo/docker-compose.yml` — Service definition
- `/opt/speedbits/matomo/config` — Matomo config
- `/opt/speedbits/matomo/logs` — Matomo logs
- `/opt/speedbits/matomo/db` — MariaDB data
- `/opt/speedbits/matomo/db_password.txt` — DB password (root‑only)

## Compose (Traefik Mode - Highlights)

```
services:
  db:
    image: mariadb:${DB_VERSION}
    networks: [ ${NETWORK}, borgmatic-db ]
    command: >
      --max-allowed-packet=64M
      --innodb-buffer-pool-size=512M

  matomo:
    image: matomo:${MATOMO_VERSION}
    environment:
      MATOMO_DATABASE_HOST: matomo-db
      MATOMO_DATABASE_ADAPTER: mysql
      MATOMO_DATABASE_TABLES_PREFIX: matomo_
      MATOMO_DATABASE_USERNAME: ${MYSQL_USER}
      MATOMO_DATABASE_PASSWORD: ${MYSQL_PASSWORD}
      MATOMO_DATABASE_DBNAME: ${MYSQL_DATABASE}
      PHP_MEMORY_LIMIT: 512M
    volumes:
      - ./config:/var/www/html/config
      - ./logs:/var/www/html/logs
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.matomo.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.matomo.entrypoints=websecure"
      - "traefik.http.routers.matomo.tls.certresolver=myresolver"
      - "traefik.http.services.matomo.loadbalancer.server.port=80"
```

## Post‑Install Tasks

- Complete the Matomo setup wizard in the browser (system check → DB → admin user → first website)
- Add the JavaScript tracking code to your site(s) (before `</head>`)
- Set up cron archiving (see below)

### Cron Archiving

```
*/5 * * * * docker exec matomo /usr/local/bin/php /var/www/html/console core:archive >/dev/null 2>&1
```

## Backup Integration (Borgmatic)

- Database container is auto‑registered with Borgmatic (if available)
- Include in backups: 
    - `/opt/speedbits/matomo/db` — MariaDB data
    - `/opt/speedbits/matomo/config` — App configuration
    - `/opt/speedbits/matomo/logs` — Optional
- Ensure Apprise notifications are configured

## Operations

```
# Logs
docker logs matomo
docker logs matomo-db

# Restart
cd /opt/speedbits/matomo && docker compose restart

# Update
cd /opt/speedbits/matomo && docker compose pull && docker compose up -d
```

## Troubleshooting

- **DB connectivity:** verify `db_password.txt`, check `matomo-db` logs
- **SSL/ACME:** check Traefik logs, DNS, ports 80/443 open
- **Performance:** tune archiving frequency; ensure DB buffer pool sizing matches workload

## Security Best Practices

- Restrict admin access; use strong credentials
- Regular updates; monitor logs
- Consider IP anonymization and consent tools for compliance

## Verification Checklist

- ✅ Matomo and database containers running
- ✅ HTTPS reachable via Traefik with valid certificate
- ✅ Setup wizard completed; admin login working
- ✅ Cron archiving running
- ✅ Backups configured and tested

## References

- [Matomo Documentation](https://matomo.org/docs/)