How to Install Matomo with Docker on Ubuntu 24.04

This guide explains how to manually install and run Matomo on an Ubuntu 24.04 server using Docker and Docker Compose. The steps follow the configuration in the supplied Matomo Ansible project.

1. Connect to the Ubuntu Server

From your computer, open PowerShell or a terminal and connect using SSH:

ssh username@SERVER_IP

Replace username with your Ubuntu username and SERVER_IP with your server's IP address.

2. Update Ubuntu

Update the package list:

sudo apt update

Upgrade installed packages:

sudo apt upgrade -y

3. Install Docker

The supplied Ansible playbook installs Docker using Ubuntu's docker.io package. Install it manually with:

sudo apt install -y docker.io

Enable Docker so that it starts automatically:

sudo systemctl enable docker

Start Docker:

sudo systemctl start docker

Check Docker's status:

sudo systemctl status docker --no-pager

You should see:

Active: active (running)

Verify the Docker version:

sudo docker --version

4. Install Docker Compose

The supplied Ansible playbook installs the Ubuntu package docker-compose-v2.

sudo apt install -y docker-compose-v2

Verify Docker Compose:

sudo docker compose version

You should receive Docker Compose version information.

5. Create the Matomo Directory

The supplied Ansible playbook creates a Matomo directory inside the current user's home directory.

First check your username:

echo $USER

Create the Matomo directory:

mkdir -p ~/matomo

Move into the directory:

cd ~/matomo

Verify the current directory:

pwd

It should look similar to:

/home/yourusername/matomo

6. Create the Docker Compose File

Create the Docker Compose configuration:

nano ~/matomo/docker-compose.yml

Paste the following configuration:

services:

  db:
    image: mariadb:11
    container_name: matomo-db
    restart: always

    environment:
      MYSQL_ROOT_PASSWORD: rootpassword
      MYSQL_DATABASE: matomo
      MYSQL_USER: matomo
      MYSQL_PASSWORD: matomopassword

    volumes:
      - db_data:/var/lib/mysql

  matomo:
    image: matomo:latest
    container_name: matomo
    restart: always

    depends_on:
      - db

    ports:
      - "8081:80"

    environment:
      MATOMO_DATABASE_HOST: db
      MATOMO_DATABASE_USERNAME: matomo
      MATOMO_DATABASE_PASSWORD: matomopassword
      MATOMO_DATABASE_DBNAME: matomo

    volumes:
      - matomo_data:/var/www/html

volumes:
  db_data:
  matomo_data:

Save the file:

• Press Ctrl + O
• Press Enter
• Press Ctrl + X

7. Check the Docker Compose Configuration

Before starting Matomo, check that the Docker Compose file is valid:

cd ~/matomo
sudo docker compose config

If the configuration is valid, Docker Compose will display the processed configuration without reporting a YAML error.

8. Download the Required Docker Images

Pull the MariaDB and Matomo images:

sudo docker compose pull

This may take several minutes depending on the Internet connection and server speed.

9. Start Matomo

Start the Matomo and MariaDB containers in the background:

sudo docker compose up -d

The -d option means that the containers run in the background.

10. Check the Running Containers

Run:

sudo docker compose ps

You should see containers similar to:

matomo
matomo-db

You can also check all running containers:

sudo docker ps

Both the Matomo and MariaDB containers should have a status showing that they are running.

11. Check the Matomo Logs

If you want to check whether Matomo started correctly, run:

sudo docker compose logs matomo

To follow the logs while the container is running:

sudo docker compose logs -f matomo

Press Ctrl + C to stop viewing the live logs. This does not stop the Matomo container.

12. Check the MariaDB Container

Check the database logs:

sudo docker compose logs db

The MariaDB container should start without repeated fatal errors.

13. Open the Matomo Web Installer

The supplied Docker Compose configuration maps:

8081:80

This means port 8081 on the Ubuntu server is connected to port 80 inside the Matomo container.

Find your server IP:

hostname -I

Then open a browser and visit:

http://SERVER_IP:8081

Replace SERVER_IP with your Ubuntu server's public IP address.

For example:

http://203.0.113.10:8081

Do not use the example IP above. Use your actual VPS IP address.

14. Complete the Matomo Web Installation

When the Matomo web installer opens, follow the on-screen installation steps. The database settings correspond to the values in the supplied Docker Compose configuration.

The database hostname is db because Docker Compose creates a network where the Matomo container can reach the MariaDB container using the service name db.

15. Check Port 8081

If the browser cannot connect, first check whether Docker is listening on port 8081:

sudo ss -lntp | grep 8081

You can also test Matomo directly from the server:

curl -I http://127.0.0.1:8081

An HTTP response indicates that something is responding on the port.

16. Configure the Firewall

If UFW is enabled on your Ubuntu server, allow port 8081:

sudo ufw allow 8081/tcp

Reload the firewall:

sudo ufw reload

Check the firewall status:

sudo ufw status

You should see port 8081/tcp allowed.

17. Useful Docker Commands

Show running containers:

sudo docker ps

Show Matomo and MariaDB containers:

cd ~/matomo
sudo docker compose ps

Restart Matomo:

cd ~/matomo
sudo docker compose restart matomo

Restart both Matomo and MariaDB:

cd ~/matomo
sudo docker compose restart

Stop the containers:

cd ~/matomo
sudo docker compose down

Warning: docker compose down stops and removes the containers, but the named volumes in this configuration are retained unless you explicitly remove them.

Start the application again:

cd ~/matomo
sudo docker compose up -d

18. View Logs When Troubleshooting

View all application logs:

cd ~/matomo
sudo docker compose logs

View Matomo logs:

sudo docker compose logs matomo

View MariaDB logs:

sudo docker compose logs db

Follow Matomo logs live:

sudo docker compose logs -f matomo

19. Check Docker Volumes

The supplied configuration stores MariaDB and Matomo data in named Docker volumes. Check them with:

sudo docker volume ls

You should find volumes associated with the Compose project, including the database and Matomo data volumes.

20. Final Verification

Run the following commands before considering the installation complete:

cd ~/matomo

sudo docker compose config

sudo docker compose ps

sudo docker ps

sudo ss -lntp | grep 8081

curl -I http://127.0.0.1:8081

If the containers are running and the server responds on port 8081, open:

http://SERVER_IP:8081

You should see the Matomo web installation/login interface.

21. Troubleshooting

Matomo page does not open

Check the containers:

sudo docker compose ps

Check the Matomo logs:

sudo docker compose logs matomo

Check whether port 8081 is listening:

sudo ss -lntp | grep 8081

MariaDB is not running

Check:

sudo docker compose ps db

Then:

sudo docker compose logs db

Docker Compose reports a YAML error

Make sure you are in the Matomo directory:

cd ~/matomo

Then run:

sudo docker compose config

This command will identify problems in the Compose configuration.

Port 8081 is already in use

Check which application is using it:

sudo ss -lntp | grep 8081

If another application is using the port, the Docker Compose port mapping would need to be changed from:

- "8081:80"

to another available host port, for example:

- "8082:80"

The browser URL would then use the new port.

22. Installation Complete

Matomo is installed using Docker with MariaDB as its database. The Matomo container uses port 8081 on the Ubuntu server, while MariaDB is accessible to Matomo through the Docker Compose service name db.

Matomo URL:

http://SERVER_IP:8081

Replace SERVER_IP with the public IP address of your Ubuntu 24.04 server.