mumblebaj/magicmirror repository overview

⁠MagicMirror Docker Image

A lightweight, customizable Docker image for MagicMirror²⁠, designed for Raspberry Pi and ARM-compatible devices. Easily extend MagicMirror with your own modules, styles, and configuration using volume mounts.

⁠🚀 Features

• Based on Debian Trixie (ARM-compatible)
• MagicMirror² version 2.37.0
• Installs Node.js 22 LTS
• Runs MagicMirror² in server-only mode
• Mount your own config.js, custom.css, and modules
• Minimal image size and build-time dependencies

⁠🧰 Usage

This assumes you have some working knowledge of linux environments

⁠🚀 Installing Docker

Before running the MagicMirror Docker container, you need to install Docker on your system.

⁠Install Docker on Raspberry Pi (Raspbian/Ubuntu)

To install Docker on your Raspberry Pi, follow these steps:

• ⁠Update the system:

sudo apt-get update
sudo apt-get upgrade -y

• ⁠Install Docker using the official script:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

• ⁠Add your user to the docker group to run Docker commands without sudo (optional but recommended):

sudo usermod -aG docker $USER

Then, log out and log back in, or reboot your Raspberry Pi.

• ⁠Verify the installation:

Check if Docker is installed correctly:

docker --version

• ⁠Start Docker:

sudo systemctl start docker

• ⁠Enable Docker to start on boot:

sudo systemctl enable docker

⁠Install Docker on Ubuntu (Desktop/Server)

• ⁠Update the system:

sudo apt-get update
sudo apt-get upgrade -y

• ⁠Install Docker dependencies:

sudo apt-get install apt-transport-https ca-certificates curl software-properties-common -y

• ⁠Add Docker’s official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

• ⁠Set up the stable Docker repository:

sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"

• ⁠Install Docker:

sudo apt-get update
sudo apt-get install docker-ce -y

• ⁠Verify the installation:

docker --version

• ⁠Allow your user to run Docker commands without sudo:

sudo usermod -aG docker $USER

Log out and log back in, or reboot your system.

⁠Install Docker on Windows (via Docker Desktop)

• Download Docker Desktop:
• Download the Docker Desktop installer from Docker's official website.
• Install Docker Desktop:
• Run the installer and follow the on-screen instructions. It may require you to enable Windows Subsystem for Linux (WSL 2), which will be prompted during installation.
• Verify the installation:
• Open a new command prompt or PowerShell window and check if Docker is installed correctly:

docker --version

⁠Install Docker on macOS

• Download Docker Desktop:
• Download the Docker Desktop installer from Docker's official website.
• Install Docker Desktop:
• Open the downloaded .dmg file and drag the Docker app to your Applications folder.
• Run Docker Desktop:
• Open Docker Desktop from your Applications folder and wait for it to initialize.
• Verify the installation:
• Open a terminal and check if Docker is installed correctly:

docker --version

⁠Create the following folder structure

⁠📂 Folder Structure

my-magic-mirror-container <-- name this to whatever you want
├── config/
│   └── config.js
├── custom-css/
│   └── custom.css
├── modules/
│   ├── MMM-ExampleModule/ <-- These are all you modules that you want to run
│   └── ...

Inside the root level of the folder create your own docker-compose.yml file

⁠🐳 Docker Compose (Recommended)

services:
  magicmirror:
    image: mumblebaj/magicmirror:latest
    container_name: magicmirror
    ports:
      - "8080:8080"
    volumes:
      - ./config:/home/pi/MagicMirror/config
      - ./custom-css:/home/pi/MagicMirror/css/custom
      - ./modules:/home/pi/MagicMirror/custom-modules
    restart: unless-stopped

• Place your config.js inside the ./config directory.

• Place your custom.css inside the ./custom-css directory.

• Clone or add modules to the ./modules directory. For the modules, ensure that you have run npm install in each module directory.

⁠🔁 Launching the Container

docker compose up -d

⁠Open your browser and navigate to:

http://localhost:8080 <-- check in your config.js what the address is set to. Ensure that  ipWhitelist: [],

⁠📦 Bringing down the container

docker compose down -v

⁠✅ License

This project is licensed under the MIT License. See LICENSE for details.

⁠🙋‍♂️ Contributing

Pull requests and issues are welcome. Feel free to fork and improve!

⁠📝 LICENSE (MIT)

MIT License

Copyright (c) 2025 [mumblebaj]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights 
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
copies of the Software, and to permit persons to whom the Software is 
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in 
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
SOFTWARE.