emoncms: logging and visualising the energy use of a building

The server side of the OpenEnergyMonitor stack

emoncms is an open source web application for processing, logging and visualising energy, temperature and other environmental data, and it is part of the OpenEnergyMonitor project. That placement defines its role. A monitoring system needs a place to keep the numbers, a place where the processing rules live, and a place to look at the result, and emoncms is the server side of that arrangement while the hardware and the emonHub are the other halves. The audience is a household or a small site that has decided to measure its own consumption, a school or community project, or a small installer who needs a server per installation rather than a hosted service. The core loop is simple and worth stating plainly, because it is what the whole application is about: inputs arrive with values, processing turns those values into feeds, and feeds are what the graphs, dashboards and reports draw from. The glossary the documentation links defines exactly those terms, input, node, feed and process, and reading it first saves a lot of confusion later.

Inputs, feeds and processes, and the API around them

The data model is small enough to understand in one sitting and expressive enough to run a real installation. The API is where that shows. Every install includes its own API reference, with API Help on the Inputs page and Feed API Help on the Feeds page, so the documentation travels with the instance rather than living on a site you might not reach. There is also a machine-readable form, since /llms-full.txt and /api.md serve the full reference as Markdown for AI assistants and other tools, and /llms.txt is a short index. The public reference pages are the Input API and the Feed API on emoncms.org. What this adds up to is that the application is designed to be driven from other programs: an emonHub posts readings to an input, a process computes a feed from inputs, and other software reads feeds out. The Docker image description names the same three services, emoncms_mqtt, service-runner and feedwriter, which is a useful confirmation of how the runtime is arranged.

Modules are the extension mechanism, and they are separate repositories

The feature set of emoncms is mostly assembled from modules, which is unusual and worth understanding. A module is installed by cloning it into the Modules folder, or into /opt/emoncms/modules with a symlink for modules that have background scripts, and then running Update Database on the Admin page after installing it. The modules shipped on the emonSD image are Graph for the feed viewer, Device for setting up inputs and feeds from device templates, Dashboard as the dashboard builder, App for ready-made dashboards such as My Electric Flow and My Heatpump, Config as the emonHub configuration editor and log viewer, Network for WiFi and network settings, Backup for backup, restore and SD card import, Sync for uploading or downloading feeds between servers, Post Process for processing recorded feed data, and Usefulscripts for maintenance scripts. Other modules include Email reports and the DemandShaper. The consequence is that the core repository is a framework and the application you actually use is assembled from about a dozen separate GitHub repositories, each with its own release cycle.

The requirements, and why shared hosting is ruled out

The system requirements are ordinary for a PHP application with a few extra services. PHP 8.1 or later, with CI testing PHP 8.1 to 8.4, and the extensions mysqli, redis, gettext, mbstring, curl, gd and xml. MySQL or MariaDB, Apache with mod_rewrite, Redis recommended, and Mosquitto for MQTT input. The Redis recommendation has a reason worth remembering: Redis reduces disk writes, which extends the life of SD cards. That matters because the primary deployment target is a Raspberry Pi with an SD card, and the wear on that card is a real operational cost. The documentation also says what is not supported. Shared hosting and XAMPP are not supported, because emoncms needs background services, which is the whole reason those environments are excluded: a shared host cannot run the long-lived processes that the input and feed pipeline depends on. A small Linux VPS works well, and the emonSD image for a Raspberry Pi is the path the project recommends for its own hardware.

Running it in a container, on Alpine, from the stable branch

There is an all-in-one Docker container, which is the fastest way to see the whole application running. It is published as alexjunk/emoncms, available for amd64, arm64 and arm/v7, and the pull is a single command:

sudo docker pull alexjunk/emoncms

The details in the description matter for anyone running this in anger. The image is built from the emoncms stable branch on Alpine Linux and is tagged with both the Alpine and the emoncms versions, so you can pin a specific combination rather than tracking latest. It bundles MariaDB, Redis and Mosquitto along with the graph, sync, backup, dashboard and app modules, and it runs the emoncms_mqtt, service-runner and feedwriter services, which is the containerised form of the three background services the shared hosting note refers to. The dedicated documentation site is emoncms-docker.github.io. The alternative routes are the EmonScripts installer documented at docs.openenergymonitor.org/emonsd/install.html, the emonSD SD card image for a Raspberry Pi, and a preloaded emonSD SD card sold by the project.

master, stable, and the Bootstrap 5 interface change

The branch structure has a specific convention that matters if you are contributing or pinning a version. The master branch is the latest development and pull requests go against it, while the stable branch is the release branch, used by emonPi and emonBase updates, with the releases listed on the repository. The Docker image is built from stable, which is a deliberate difference between what a container gives you and what the development branch holds. Version 12 is a notable step because it moves the interface to Bootstrap 5, with the release notes in docs/developer/notes/bootstrap5-release.md. The current release line in the repository is 12.1.7 from 2026-10-09, and the last push was on 2026-10-11, so the project is being worked on continuously. The rest of the tree supports that: a devcontainer directory, composer.json and composer.lock, a .phpcs.xml for coding standards, a .jshintrc for the JavaScript side, tests/, an AGENTS.md and a CLAUDE.md, and a service-worker.js for offline use of the interface.

Editorial conclusion

Adopt emoncms if you are running OpenEnergyMonitor hardware or an equivalent set of inputs and need a self-hosted place to store, process and chart the data over years. Do not adopt it if you need shared hosting or a PHP-only environment, because the documentation states plainly that shared hosting and XAMPP are not supported since emoncms needs background services. Before you install, decide between the emonSD image for a Raspberry Pi and the all-in-one Docker container, and note that the container is built from the stable branch rather than master, and that the last push was on 2026-10-11 with the current release at 12.1.7.

Frequently asked questions

Official sources

1. emoncms/emoncms on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases