From abbda9d865081b2076f694bacb96d41e8d544dd9 Mon Sep 17 00:00:00 2001 From: MassiveBox Date: Fri, 19 Apr 2024 17:09:28 +0200 Subject: [PATCH] Add pages --- Admin Panel.md | 35 +++++++++++++++++++++++++ Advanced Configuration.md | 6 +++++ Building.md | 25 ++++++++++++++++++ HomeAssistant Setup.md | 11 ++++++++ Installing on Docker.md | 55 +++++++++++++++++++++++++++++++++++++++ Installing on Linux.md | 50 +++++++++++++++++++++++++++++++++++ _Footer.md | 3 +++ _Sidebar.md | 11 ++++++++ 8 files changed, 196 insertions(+) create mode 100644 Admin Panel.md create mode 100644 Advanced Configuration.md create mode 100644 Building.md create mode 100644 HomeAssistant Setup.md create mode 100644 Installing on Docker.md create mode 100644 Installing on Linux.md create mode 100644 _Footer.md create mode 100644 _Sidebar.md diff --git a/Admin Panel.md b/Admin Panel.md new file mode 100644 index 0000000..db21f7a --- /dev/null +++ b/Admin Panel.md @@ -0,0 +1,35 @@ +# ⚙️ Admin Panel + +The Admin Panel is the right place to configure and customize EcoDash. + +## How to access the Admin Panel + +After installing and starting EcoDash, you will have the server running on the port you specified of the local IP address of the machine on which EcoDash is running. +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.yourdomain.com/`. +- **HomeAssistant's API Key**: Read [HomeAssistant Setup](./HomeAssistant Setup) to learn how to get it. +- **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. + diff --git a/Advanced Configuration.md b/Advanced Configuration.md new file mode 100644 index 0000000..d631a45 --- /dev/null +++ b/Advanced Configuration.md @@ -0,0 +1,6 @@ +# 📚 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. + diff --git a/Building.md b/Building.md new file mode 100644 index 0000000..b63190f --- /dev/null +++ b/Building.md @@ -0,0 +1,25 @@ +# 👷 Building EcoDash + +Here's how to build EcoDash in both binaries and as a Docker container. This is not necessary for most cases - we provide both pre-built binaries and containers for Linux ARM and x86_64 - however in devices with unsupported architectures it's necessary. + +You're encouraged to first check the installation instructions to see if a pre-built container or binary is already available. +If you really have to build it yourself, we recommend you Docker over binaries. + +### Setup + +1. Download Git for your operating system from https://git-scm.com/download or from your package manager (it's nearly always called `git`) +2. Clone the repository by running `git clone https://git.massivebox.net/massivebox/ecodash.git ` inside a command prompt +3. Switch to the project directory with `cd ecodash` +4. If you want to build the latest stable release (recommended), use `git tag` to list all the available release version, then `git checkout VERSION` where `VERSION` is the highest available release as listed by `git tag`. + +### Binaries + +1. Download the Go Compiler from https://go.dev/dl/ or from your package manager (it's usually called `go` or `golang`) +3. Download `golangci-lint` from https://golangci-lint.run/ (optional) +6. Run `golangci-lint run` to lint all project files (optional) +7. Build with `go build src/main/main.go -o ecodash`. This will generate an executable, `ecodash` or `ecodash.exe` if you're in Windows, in the same directory. + +### Docker + +1. Download and install Docker Engine (recommended) or Docker Desktop from https://www.docker.com/ or from your package manager (it's nearly always called `docker`) +2. Run `docker build . -t git.massivebox.net/massivebox/ecodash`. This will build the image and tag it as `git.massivebox.net/massivebox/ecodash:latest`, which allows you to use the image according to the documentation. diff --git a/HomeAssistant Setup.md b/HomeAssistant Setup.md new file mode 100644 index 0000000..c8e4ff3 --- /dev/null +++ b/HomeAssistant Setup.md @@ -0,0 +1,11 @@ +# 🏠 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. diff --git a/Installing on Docker.md b/Installing on Docker.md new file mode 100644 index 0000000..ed464d6 --- /dev/null +++ b/Installing on Docker.md @@ -0,0 +1,55 @@ +# 🐳 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](./Building) guide. + +### Tags + +In the examples below, the Docker image is linked as `git.massivebox.net/massivebox/ecodash:latest`. +The part after the colon is the _tag_, which defines which version of the software to use. You can change it from `latest` to one of the supported tags below, according to the level of stability you desire: + +- `latest`: tracks the latest stable release. Should be fine for most cases. +- `master`: tracks the latest update to the code in the `master` branch of the repository. Might be less stable. +- `vA`: tracks the latest release with the major version number being `A` +- `A.B`: tracks the latest release with the major version number being `A` and minor version being `B` +- `A.B.C`: tracks the release with the specified version. + +Consult all the available versions [here](https://git.massivebox.net/massivebox/-/packages/container/ecodash/versions). + +## With Docker command-line + +```bash +docker run -v /absolute/path/to/data/folder:/app/data --name ecodash -p 8080:80 git.massivebox.net/massivebox/ecodash:latest +``` + +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: + +```yaml +version: '3' +services: + ecodash: + ports: + - 8080:80 + container_name: ecodash + image: git.massivebox.net/massivebox/ecodash:latest + volumes: + - ./data:/app/data + restart: always +``` + +Run the container with + +```bash +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://git.massivebox.net/massivebox/ecodash.rss diff --git a/Installing on Linux.md b/Installing on Linux.md new file mode 100644 index 0000000..f024490 --- /dev/null +++ b/Installing on Linux.md @@ -0,0 +1,50 @@ +# 🐧 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](./Building) guide. + +## Download + +1. Grab the appropriate ZIP from the [latest release page](https://git.massivebox.net/massivebox/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 or errors. 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 the service starts successfully, 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://git.massivebox.net/massivebox/ecodash.rss diff --git a/_Footer.md b/_Footer.md new file mode 100644 index 0000000..6dec50e --- /dev/null +++ b/_Footer.md @@ -0,0 +1,3 @@ +Copyright © 2024 MassiveBox. +Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections. +A copy of the license can be found at https://www.gnu.org/licenses/fdl-1.3.html diff --git a/_Sidebar.md b/_Sidebar.md new file mode 100644 index 0000000..624394d --- /dev/null +++ b/_Sidebar.md @@ -0,0 +1,11 @@ +### 🌿 EcoDash + +- [📖 Home](./Home) +- [👷 Building from Source](./Building) +- Installing + - [🐳 Docker](./Installing%20on%20Docker) + - [🐧 Linux](./Installing%20on%20Linux) +- Configuration + - [🏠 HomeAssistant Setup](./HomeAssistant%20Setup) + - [⚙️ Admin Panel](./Admin%20Panel) + - [📚 Advanced Configuration](./Advanced%20Configuration)