Initial commit

docs/ezodash.md

@@ -0,0 +1,15 @@
+---
+unlisted: true
+---
+
+# 🍀 EZoDash - EcoDash simplified
+
+EcoDash has the great strength of being widely compatible, but that comes at the cost of forcing our users to spend more time configurating their setup. It also forces users to use a compatibility layer - HomeAssistant - which standardizes the different home plugs into one simple language that EcoDash can understand. Running it represents a significant overhead for admins who are only using it for EcoDash - especially the ones running less capable devices.
+
+Since most potential users of EcoDash don't have a smart plug and are already running Linux on their homeserver, we've thought of creating a much lighter compatibility layer for EcoDash which works with only a single type of smart plugs - one which is usually very cheap and completely cloud-free.
+
+We've opted for Zigbee-compatible plugs such as [this one](https://www.aliexpress.com/item/1005002344798281.html). A smart plug and the [USB stick](https://www.aliexpress.com/w/wholesale-zigbee-usb-dongle.html) which is required to read and send data to it will cost only about ~€15.
+
+EZoDash will be a component of EcoDash, not a separate project. EcoDash will still be compatible with HomeAssistant in order to support all different smart plug types.
+
+EZoDash will be released before v1.0.

docs/index.md

@@ -0,0 +1,28 @@
+---
+sidebar_position: 0
+---
+
+# 📖 Introduction
+
+Empower your end users with EcoDash - the accessible and user-friendly  power usage monitoring tool. Our public dashboard provides clear and  concise information about server energy consumption, with  easy-to-understand comparisons that make energy usage tangible. By using EcoDash, you can increase transparency and accountability around energy consumption, and help drive sustainable practices in your organization.
+
+## F.A.Q.
+
+### How does it work?
+
+Since most consumer-grade hardware isn't equipped with internal energy consumption sensors, we've opted to make EcoDash work with external sensors - smart energy monitoring plugs.
+
+EcoDash reads data trough an external component - HomeAssistant (default) or [EZoDash](/docs/ezodash) (coming soon) - and logs it into its database.
+
+### Who is it for?
+
+EcoDash is for everyone with a homeserver who wants to be completely trasparent towards their users about how much their server consumes. You can think of it like an uptime status page - while it's not strictly necessary, it can help your users see that they're trusting a reliable and environmentally-conscious person or organization.
+
+### What devices are compatible?
+
+Since EcoDash currently uses HomeAssistant as its intermediary to talk with smart plugs, it supports all the devices supported by HomeAssistant.
+
+There is no official list of supported plugs. [This](https://www.hadevices.com/category/power) is a starting point, but it doesn't include non-US plugs and Zigbee devices.
+
+EcoDash's main developer is using [this](https://www.aliexpress.com/item/1005002344798281.html) Zigbee plug and [this](https://www.aliexpress.com/item/1005003606832844.html) gateway.
+

docs/install/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "⬇️ Install",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Here's how to install EcoDash on different platforms. Choose yours from the list below. Docker is the recommended one, as it's platform-independent.",
+    "slug": "/install",
+  }
+}

docs/install/docker.md

@@ -0,0 +1,46 @@
+# 🐳 Docker
+
+Docker is the recommended deployment method for EcoDash. It allows to run on different architectures and operating systems without hassle.
+
+Pre-built Docker containers are offered for Linux on ARM and x86_64. If you're not on a supported architecture or operating system, please check the [Building the container](https://gitea.massivebox.net/ecodash/ecodash/src/branch/master/BUILD.md) guide.
+
+## With Docker command-line
+
+```
+docker run -v /absolute_path_to/config.json:/app/config.json -v /absolute_path_to/database.db:/app/database.db --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.
+
+## With 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
+      - ./database.db:/app/database.db
+    restart: always
+```
+
+Run the container with
+
+```
+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.
+
+## Get notified about new releases
+
+Since EcoDash doesn't have any way to notify admins of new releases, you're encouraged to add our repository's feed into your RSS reader: https://gitea.massivebox.net/ecodash/ecodash.rss
+
+
+

docs/install/linux.md

@@ -0,0 +1,59 @@
+# 🐧 Linux
+
+Pre-built binaries are available for Linux systems with x86_64 and ARM architecture. They should work on any distribution, but haven't been tested on all. Please open an issue if problems arise.
+
+If you're not on a supported architecture, please check the [Building on Linux](https://gitea.massivebox.net/ecodash/ecodash/src/branch/master/BUILD.md) guide.  
+The [docker image](/docs/install/Docker) is recommended over running from binaries.
+
+## Download
+
+1. Grab the appropriate ZIP from the [latest release page](https://gitea.massivebox.net/ecodash/ecodash/releases/latest). Make sure to select the right file for your architecture:  
+   `wget LINK_TO_APPROPRIATE_FILE`
+2. Extract the contents. This will create a folder named `ecodash` in the current directory, which will contain the binary, the configuration, the database and HTML templates folder:  
+   `unzip FILE_NAME`
+3. To start the container, first enter the `ecodash` directory:  
+   `cd ecodash`  
+   Then run it. This will expose EcoDash on port 80 by default:  
+   `./ecodash`  
+   If you want to run on any other port, use an environment variable like this:  
+    `env PORT=8080 ./ecodash`
+
+## Set up auto-restart
+
+You might want your EcoDash server to restart automatically in the event of system reboots, programming bugs or configuration saves. This tutorial only covers distributions with systemd.
+
+1. Create a file at `/etc/systemd/system/ecodash.service` with this content:
+   ```
+   [Unit] 
+   Description=EcoDash
+   After=network.target 
+   StartLimitIntervalSec=0 
+   
+   [Service] 
+   Type=simple 
+   Restart=always 
+   User=USER 
+   ExecStart=EXTRACTION_PATH/ecodash/ecodash
+   
+   [Install] 
+   WantedBy=multi-user.target
+   ```
+
+   Make sure to replace USER with your username and EXTRACTION_PATH with the path where you performed the `wget` earlier.
+
+2. Test if it works:  
+   `systemctl start ecodash`
+
+3. If it does (you don't see any error) you can set the OS to automatically start it after reboots with this:  
+   `systemctl enable ecodash`
+
+## Get notified about new releases
+
+Since EcoDash doesn't have any way to notify admins of new releases, you're encouraged to add our repository's feed into your RSS reader: https://gitea.massivebox.net/ecodash/ecodash.rss
+
+## Moving on
+
+Now that EcoDash is installed, you can proceed to the Setup.
+
+
+

docs/install/windows.md

@@ -0,0 +1,3 @@
+# 🪟 Windows
+
+Pre-built binaries or Docker images are not yet offered for Windows. You are encouraged to use WSL or [build yourself](https://gitea.massivebox.net/ecodash/ecodash/src/branch/master/BUILD.md) the Docker container for Windows. Support for this operating system and related documentation will come in future releases.

docs/roadmap.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 1
+---
+
+# 🛣 Roadmap
+
+You can monitor our progress here:
+
+<iframe src="https://kanboard.massivebox.net/public/board/aa1008cd9b368fe13d84b22fe3a0b1c7cdea0a9a984417642d933922b5cb" width="100%" height="700px"/>
+
+### Columns
+
+- `Backlog` is for features on which the ones in `Ready` depend on
+- `Ready` is for features which have all requirements completed
+- `Work In Progress` is for features which are being worked on but haven't been committed
+- `Done` is for features which are committed but not in a stable release. Once a feature is released, it is removed from the board.
+
+### Tags
+
+- `v*` means that the feature will be included in that version
+- `next` means the feature will be in the next stable release
+- untagged means the feature has no ETA
+
+
+
+
+

docs/setup/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "⚙️ Setup",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn how to configure EcoDash, from the basics to the most advanced settings. If you're just getting started, follow the tutorials in this section in order.",
+    "slug": "/setup",
+  }
+}

docs/setup/admin-panel.md

@@ -0,0 +1,39 @@
+---
+sidebar_position: 2
+---
+
+# ⚙️ Admin Panel
+
+The Admin Panel is the right place to configure and customize EcoDash.
+
+## How to access the Admin Panel
+
+If this is the first time you've run EcoDash, you will load directly into the Admin Panel, and you won't be able to leave it until you've changed the settings.
+
+After the first run, click the "Admin" button in the left side of the navbar, or in the hamburger menu from mobile devices.
+
+If you do not see that button, you can still access the admin panel by appending "/admin" to the URL of your EcoDash homepage.
+
+## Configuration
+
+### HomeAssistant
+
+- **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**:
+- **Installation date**: Select the date of the first day in which your server's consumption was  logged in its entirety. Users won't be able to see consumption data  before this date.
+
+### Sensors
+
+- **Polled Smart Energy Summation entity ID**: After your plug is added in HomeAssistant, get it in Settings -> Devices & Services -> Select the smart plug (or the Zigbee dongle -> Smart plug) -> 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**: After the CO2 Signal integration is enabled in HomeAssistant, get it in Settings -> Devices & Services -> CO2 Signal "2 entities" -> CO2 signal Grid fossil fuel percentage -> Settings -> Copy the Entity ID.  Check that the unit of measurement in the "Info" tab is %.
+
+### Admin account
+
+- **Username**: The username which you will have to enter the Admin Panel. Note it doesn't have to be the same as HomeAssistant.
+- **Password**: The password which you will have to enter the Admin Panel. Note it doesn't have to be the same as HomeAssistant.
+
+### Personalization
+
+- **Theme**: This setting will allow you to change the theme. There are no alternative themes at the moment.
+- **Dashboard name**: This will change the name shown in the top-left corner of the screen.
+

docs/setup/advanced.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 3
+---
+
+# 📚 Advanced configuration
+
+This section describes how to customize EcoDash beyond the Admin Panel's limits. It's not necessary to change these settings.
+
+This section is still a work in progress. It will be published before release v1.

docs/setup/ecodash.md

@@ -0,0 +1,15 @@
+---
+sidebar_position: 1
+---
+
+# 🏠 HomeAssistant Setup
+
+EcoDash requires HomeAssistant to run. Its purpose is translating the protocols that different smart plugs use into a simple universal HTTP API that EcoDash can use.
+
+1.  Install HomeAssistant: follow [this](https://www.home-assistant.io/installation/) guide. The installation method you choose doesn't matter.
+2. Add your smart energy monitor. Go to Settings -> Devices and Services -> Add Integration -> Choose your device type. Follow [this](https://www.home-assistant.io/integrations/zha/#configuration---gui) guide for Zigbee devices.
+3. Generate an API Key for EcoDash:
+   1. Go to your profile (bottom left of the page - click on your account name)
+   2. Scroll to "Long-Lived Access Tokens"
+   3. Press "Create token", give it a name and click OK
+   4. Copy the token and paste it in a safe place.

docs/support.md

@@ -0,0 +1,31 @@
+---
+sidebar_position: 4
+---
+
+# 🆘 Support
+
+You can get support for EcoDash on the following channels:
+
+- [Matrix](https://matrix.to/#/#ecodash-support:massivebox.net)
+
+- [Telegram](https://t.me/ecodash_support)
+
+- [Issues on Gitea](https://gitea.massivebox.net/massivebox/ecodash/issues)
+
+- [support@ecodash.xyz](mailto:support@ecodash.xyz)
+
+The Matrix and Telegram rooms are bridged toghether, meaning that users of either one can read and respond to the messages in the other.
+
+Before asking others, you're encouraged to search for your issue in the chat history and in the repository's issues tab.
+
+## 📐 Rules
+
+The following rules apply on all support channels.
+
+- **Be patient**: since EcoDash's community is small (for now!), it might take time to get an answer that is right for you. 
+
+- **Be inclusive and polite**: EcoDash's community aims to be made of all kinds of people. Help us building a diverse community by being inclusive, avoiding discrimination and political talk in general.
+
+- **Stay on topic**: support channels don't allow for discussion which is not related to EcoDash.
+
+- **Content rules**: only safe-for-work content is allowed. Content which is illegal under Italian laws is strictly forbidden.