Full installation guide

Use this guide when you want full control (custom paths, forks, air-gapped steps) or when the Quick start installer fails and you need to reproduce each step by hand.

Prerequisites

Raspberry Pi OS (64-bit) updated (sudo apt update && sudo apt upgrade -y).
Git, build tools, and Python 3 with venv.
A non-root user in the sudo group.

ℹ️ Note: Commands below assume the upstream repository TorNation01/magicmirror2os. Replace URLs if you maintain a private fork.

1. Install system packages


sudo apt install -y git curl ca-certificates build-essential \
  python3 python3-venv python3-pip pkg-config

2. Install Node.js 20

Using NodeSource (common on Pi OS):


curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v   # expect v20.x

3. Clone M2C2 (MagicMirror2 OS)

Pick an install directory (example: ~/magicmirror2os):


export M2C2_HOME="$HOME/magicmirror2os"
git clone https://github.com/TorNation01/magicmirror2os.git "$M2C2_HOME"
cd "$M2C2_HOME"

4. Install Node dependencies


npm install

If the repository documents native addons, install any extra apt packages it lists (for example libudev-dev).

5. Python virtual environment (if the repo ships Python services)


python3 -m venv .venv
source .venv/bin/activate
if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
deactivate

💡 Tip: Some releases run Python via systemd user units; check the repository’s docs/ or scripts/ for the supported layout.

6. PM2 process manager


sudo npm install -g pm2
cd "$M2C2_HOME"

If the project includes ecosystem.config.cjs / ecosystem.config.js:


pm2 start ecosystem.config.cjs

Otherwise start the npm script (adjust name to match package.json):


pm2 start npm --name m2c2 -- start
pm2 save
pm2 startup systemd -u "$USER" --hp "$HOME"

Run the printed sudo env PATH=... command so PM2 resumes on boot.

7. Kiosk mode (Chromium fullscreen)

Install Chromium if needed: sudo apt install -y chromium-browser (package name may be chromium on newer Pi OS).
Create autostart entry ~/.config/autostart/m2c2-kiosk.desktop:


[Desktop Entry]
Type=Application
Name=M2C2 Kiosk
Exec=chromium-browser --kiosk --incognito http://127.0.0.1:3000
X-GNOME-Autostart-enabled=true

Replace the URL/port with the value from your package.json or server config.

⚠️ Warning: Kiosk mode on a shared family PC can lock users out of the desktop. Prefer a dedicated Pi for wall mounting.

8. Reboot test


sudo reboot

After reboot you should have PM2 running the server and Chromium opening the mirror UI.

Troubleshooting

Port already in use
Change PORT in environment or stop conflicting services (sudo lsof -i :3000).

GPU / WebGL glitches
Increase GPU memory in raspi-config → Performance → GPU Memory (try 128 or 256 MB).

White screen in Chromium
Disable hardware acceleration flags or update Pi OS; confirm the app responds at curl -I http://127.0.0.1:3000.