ecodash/README.md
2022-10-26 21:48:36 +02:00

102 lines
4.7 KiB
Markdown

# 🌿 EcoDash
EcoDash is a simple way to show your users how much your server consumes.
It's intended as a medium of transparency, that gives your users an idea about the consumption of your machine. It's not meant to be 100% accurate.
You can see it in action here: https://ecodash.massivebox.net
## Requirements
- A working HomeAssistant installation
- An energy consumption sensor, such as a [smart plug](https://www.aliexpress.com/item/1005003188500978.html), to which your server is plugged in and connected.
- CO2 Signal added as integration into HomeAssistant
## Installation
#### Using Docker run:
```
touch config.json
docker run -v ./config.json:/app/config.json --name ecodash -p 8080:80 gitea.massivebox.net/massivebox/ecodash
```
This will open the container on port 8080. Replace "8080" in the command with whatever number you want to open that specific port.
#### Using Docker Compose:
Create a file `docker-compose.yml` with the following content:
```
version: '3'
services:
ecodash:
container_name: ecodash
image: gitea.massivebox.net/massivebox/ecodash
ports:
- '8080:80'
volumes:
- ./config.json:/app/config.json
restart: always
```
Run the container with
```
touch config.json
docker compose up -d
```
This will open the container on port 8080. Replace "8080" in the file with whatever number you want to open that specific port.
#### Using the binary
Grab a binary from the Releases page and run it. You can use the `PORT` environment variable to override the default port (80).
## Set up
As soon as you navigate to the container's exposed port, you will see the admin dashboard, there you will have to fill all fields to get EcoDash running.
- **HomeAssistant's base URL**: the base URL which you use to access HomeAssistant on your server. It should be something like `http://INTERNAL_IP_ADDRESS:8123/` or `https://homeassistant.youdomain.com/`.
- **HomeAssistant's API Key:** Get it by going into your HomeAssistant profile settings (at `http://HOMEASSISTANT-BASE-URL/profile`) -> Create Long Lived Access Token (at the very bottom of the page) -> Insert a name -> Copy the string it gives you
- **Polled Smart Energy Summation entity ID:** After your plug is added in HomeAssistant, get it in Overview -> look for an entity called like "[Name of your plug] Polledsmartenergysummation" -> Settings -> Copy the Entity ID. Check that the unit of measurement in the "Info" tab is kWh.
- **CO2 signal Grid fossil fuel percentage entity ID**: Get it in Settings -> Devices and Integrations -> Add Integration -> CO2 Signal -> Get your token from the website -> CO2 signal Grid fossil fuel percentage -> Settings -> Copy the Entity ID. Check that the unit of measurement in the "Info" tab is %.
- **Admin username and password** don't need to be the credentials to HomeAssistant! They are the credentials to log into the admin panel.
If you've just added your energy meter into HomeAssistant, note that it will take eight days for EcoDash to show meaningful data.
## Support
If something isn't working, you can find some help here:
- [Matrix support room](https://matrix.to/#/#support:massivebox.net)
- [Issues page](./issues)
- [Contact me](https://massivebox.net/contact.html)
## The road ahead
EcoDash is currently released as a minimum viable product, still far from completion. Here's a non-extensive, unordered list of the changes I want to make.
- Adding support for energy returns (like solar panels)
- Supporting hot reload, removing the need to restart EcoDash each time the settings are changed
- Improving clarity for when data is missing
- Making FossilFuel Percentage optional and adding other sources
- Supporting energy consumption readings from internal sensors
- Adding some way to change header/footer links directly from the admin panel
- Eventually being completely HomeAssistant-independent
- Adding Woodpecker CI
- Organizing branches and releases better
- Moving documentation to a wiki and expanding it
- Extensively documenting the theming capabilities of EcoDash
- Publishing some alternative themes
## License
```
EcoDash
Copyright (C) 2022 MassiveBox
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
```