diff --git a/docs/installation/_category_.json b/docs/installation/_category_.json index 88ca9359a3..e11128926d 100644 --- a/docs/installation/_category_.json +++ b/docs/installation/_category_.json @@ -1,4 +1,4 @@ { - "label": "Erste Schritte", + "label": "Installation", "position": 2 } diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/_category_.json b/i18n/en/docusaurus-plugin-content-docs/current/installation/_category_.json new file mode 100644 index 0000000000..e11128926d --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/installation/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Installation", + "position": 2 +} diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/docker.mdx b/i18n/en/docusaurus-plugin-content-docs/current/installation/docker.mdx new file mode 100644 index 0000000000..2e7386b6fc --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/installation/docker.mdx @@ -0,0 +1,227 @@ +--- +sidebar_position: 4 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Docker / containerd + +evcc can be installed as a Docker / Container image. This also works on some common NAS systems, such as Synology. + +:::important +Using Docker can require some more advanced system knowledge - beginners might want to stick to one of the other installation options. + +This guide refers specifically to Docker / Synology. Details may differ with other systems, such as cri and podman. +::: + +:::warning +Some devices and communication options won't work without specialized docker configuration options, which may not be covered in this guide. +:::warning + +:::tip +It's a good idea to test your configuration and setup in a non-docker environment first, to rule out any issues not related to containerisation. +::: + +:::note +At the moment, only the following CPU architectures are supported: + +* AMD64 +* ARMv6 +* aarch64 +::: + +## Configuration + +1. It's best to start with a known-working evcc setup using one of the other installation methods: + + - [Debian, Ubuntu, Raspberry Pi](linux) + - [macOS](macos) + - [Manual Installation (including Windows)](manual) + + :::note + Where possible, we recommend carrying out this initial setup on the same system that you plan to run containerised evcc on. + ::: + +2. If necessary, copy your resulting `evcc.yaml` to the system that you intend to run Containerised evcc on. +3. Create a directory to store evcc's SQLite database (e.g `~/.evcc`). + +## Installation + +The Container can either be created manually via the command line, or using a `docker-compose` file. + +### Command Line + +Start the container using one of the following commands: + + + + +```sh +docker run \ +-d \ +--name evcc \ +-v $(pwd)/evcc.yaml:/etc/evcc.yaml \ +-v $(pwd)/.evcc:/root/.evcc \ +-p 7070:7070 \ +-p 8887:8887 \ +-p 7090:7090/udp \ +-p 9522:9522/udp \ +evcc/evcc:latest +``` + + + + evcc requires a static Machine ID when using SMA Sunny Home Manager. If this applies to you, append the following to your command: + +``` +--network host +-v /etc/machine-id:/etc/machine-id \ +``` + +Alternatively, you can define a Machine ID under the `plant` key in your `evcc.yaml`. + + + + +:::note +The following image tags are used: +* `evcc/evcc:latest` for the current stable release. (recommended) +* `evcc/evcc:nightly` for the latest, potentially unstable build. +::: + +:::note +Depending on your installation, you may need to prepend `docker` commands with `sudo`. +::: + +:::note +The `-d` flag will automatically destroy the evcc container once it has stopped. You'll then need to relaunch it again with the same command. +::: + +:::warning +**Never** mount the host's `/etc` directory as a volume to the container, only specific configuration files! +::: + +### With [docker-compose](https://docs.docker.com/compose) + +[docker-compose](https://docs.docker.com/compose) has some useful advantages over using the command line, especially if you want to combine other applications (such as træfik) with evcc. + +Simply copy the following configuration into a `docker-compose.yaml` in your working directory: + + + + + version: "3" + services: + evcc: + command: + - evcc + container_name: evcc + image: evcc/evcc:latest + ports: + - 7070:7070/tcp + - 8887:8887/tcp + - 7090:7090/udp + - 9522:9522/udp + volumes: + - /etc/evcc.yaml:/etc/evcc.yaml + - /home/[user]/.evcc:/root/.evcc + restart: unless-stopped + + + + + network_mode: host + volumes: + - /etc/machine-id:/etc/machine-id + - /var/lib/dbus/machine-id:/var/lib/dbus/machine-id + + + + +Now start the container: + +```sh +docker-compose up -d +``` + +This will remain in the background until you stop it. + +## Useful Commands + +- Show all containers: + + ```sh + docker ps -a + ``` + +- Get the logs from the evcc container: + + ```sh + docker logs evcc + ``` + +- Validate the meter configuration: + + ```sh + docker exec evcc evcc -l debug meter + ``` + +- Validate the charger configuraiton: + + ```sh + docker exec evcc evcc -l debug charger + ``` + +- Validate the vehicle configuration: + + ```sh + docker exec evcc evcc -l debug vehicle + ``` + +You should be able to find the evcc interface at `http://127.0.0.1:7070`. + +:::note +Replace `127.0.0.1` with the IP address or hostname of the system you're running evcc on, if appropriate. +::: + +## Upgrades + +To update to the latest version of evcc, follow this guide: + +- Open a Terminal + +- Get the latest release of evcc (changing the tag if appropriate): + + ```sh + docker pull evcc/evcc:latest + ``` + +- Stop and remove the evcc container: + + ```sh + docker stop evcc + docker rm evcc + # or + docker-compose down + ``` + +- Restart the container using the appropriate incantation above. + +## NAS systems + +### Synology NAS + +You can install evcc via Docker on Synology NAS systems using its graphical interface, without using the command line. +You'll be given the choice of two network modes: bridge, or host. Whether the Bridge mode can be used depends on what components you're using, and how they communicate with your equipment. +In case of doubt, use host mode. Further information can be found in this useful PDF: +(DE) [Anleitung.EVCC.Synology.Docker.Elli.Charger.Connect-Pro.pdf](https://github.com/evcc-io/docs/files/10365841/Anleitung.EVCC.Synology.Docker.Elli.Charger.Connect-Pro.pdf) + +More information on Bridge Mode can be found here: +(DE)[EVCC_Synology_Docker-2.pdf](https://github.com/evcc-io/docs/files/10365845/EVCC_Synology_Docker-2.pdf) (erstellt von at4hawo1) + +#### QNAP NAS + +Installing evcc on QNAP systems via Docker is very similar to the above Synology instructions. +Further QNAP specific instructions can be found here: +(DE) [EVCC_auf_QNAP_Container_Station.pdf](https://github.com/evcc-io/docs/files/11241693/EVCC_auf_QNAP_Container_Station.pdf) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/index.md b/i18n/en/docusaurus-plugin-content-docs/current/installation/index.md new file mode 100644 index 0000000000..af20cd1295 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/installation/index.md @@ -0,0 +1,14 @@ +--- +sidebar_position: 1 +--- + +# Installing evcc + +Setting up evcc currently requires a bit of technical knowledge - but if you're familiar with the basics of the terminal, and you're not afraid of configuration files, then you'll be absolutely fine. + +Pick your platform of choice and we'll guide you through setting up! + +- [Linux (Debian, Ubuntu, Raspberry Pi OS)](linux) +- [macOS](macos) +- [Docker (incl. Synology)](docker) +- [Manual Installation (including Windows)](manual) diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/linux.mdx b/i18n/en/docusaurus-plugin-content-docs/current/installation/linux.mdx new file mode 100644 index 0000000000..7b69954ea9 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/installation/linux.mdx @@ -0,0 +1,200 @@ +--- +sidebar_position: 2 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Linux (Debian, Ubuntu, Raspberry Pi) + +:::caution +This guide is aimed specifically at APT-based distributions. For distributions using other package managers, please install using [Docker](docker) or [Manual Installation](manual). +::: + +## Installation Guide + +:::note +The "evcc" user is created during installation - please make sure this user doesn't already exist! +::: + +- Open a terminal +- Install required dependencies: + + ```sh + sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl + ``` + +- Add the evcc APT repository: + + + + Current stable release + +```sh +curl -1sLf \ + 'https://dl.cloudsmith.io/public/evcc/stable/setup.deb.sh' \ + | sudo -E bash +``` + + + + Nightly release, with the latest (potentially unstable!) code + +```sh +curl -1sLf \ + 'https://dl.cloudsmith.io/public/evcc/unstable/setup.deb.sh' \ + | sudo -E bash +``` + + + + +:::note +[![Hosted By: Cloudsmith](https://img.shields.io/badge/OSS%20hosting%20by-cloudsmith-blue?logo=cloudsmith&style=flat-square)](https://cloudsmith.com) + +We would like to thank [Cloudsmith](https://cloudsmith.com) for hosting the repository! +Cloudsmith provides services to support the development of free software and platforms. +::: + +- Update the package list: + + ```sh + sudo apt update + ``` + +- Install evcc: + + ```sh + sudo apt install -y evcc + ``` + +- Start the evcc server: + + ```sh + sudo systemctl start evcc + ``` + +- Now check the installation by opening a browser to `http://localhost:7070`. You should see the evcc web interface in demo mode. + +- Stop the server: + + ```sh + sudo systemctl stop evcc + ``` + +- You can now start the configuration wizard - simply follow the prompts in your terminal! + + ```sh + evcc configure + ``` + + Once all devices are configured, you can continue on. + + :::tip + The Configuration wizard is not available under the Home Assistant environment. + You may find it easier to install evcc on another Windows or Linux system, use `evcc configure` there, and then copy the generated _evcc.yaml_ to the desired system. + ::: + + :::note + Advanced users (those with evcc experience & some technical know-how) might want to use the advanced configurator: + + ```sh + evcc configure --advanced + ``` + + This mode offers some further, more technically-involved options. + ::: + +- Test to make sure your new configuration works: + + ```sh + evcc -c evcc.yaml + ``` + + Open a browser and head to `http://localhost:7070`: the evcc interface should now show your own devices. + +- If everything's working, press `CTRL+C` to stop the server. + +- Move the generated configuration to its home: + + ```sh + sudo mv evcc.yaml /etc + ``` + +- Start evcc: + + ```sh + sudo systemctl start evcc + ``` + +- Go back to your browser and refresh to make sure everything's working as it should be! + +## Upgrades + +To update to the latest version of evcc, follow this guide: + +- Open a terminal +- Update the package list: + + ```sh + sudo apt update + ``` + +- Upgrade evcc: + + ```sh + sudo apt --only-upgrade install -y evcc + ``` + +## Downgrade + +If you need to go backwards for any reason, you can do so with this command: + +```sh + sudo apt install evcc=x.xxx.x # Version Number +``` + +## Managing the Service + +evcc runs as a background system service. Here's some useful commands to control it: + +```sh +sudo systemctl status evcc # shows status +sudo systemctl start evcc # start the service, if it isn't already running +sudo systemctl stop evcc # stops the service +sudo systemctl restart evcc # restart the service +sudo systemctl enable evcc # sets the service to run at boot +sudo systemctl disable evcc # stops the service running at boot +``` + +## Useful Commands + +- Show the service status: + + ```sh + sudo systemctl status evcc + ``` + +- Show all log entries since yesterday: + + ```sh + sudo journalctl -u evcc --since "yesterday" + ``` + +- Validate the meter configuration: + + ```sh + sudo evcc -l debug meter + ``` + +- Validate the charger configuration: + + ```sh + sudo evcc -l debug charger + ``` + +- Validate the vehicle configuration: + + ```sh + sudo evcc -l debug vehicle + ``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/macos.md b/i18n/en/docusaurus-plugin-content-docs/current/installation/macos.md new file mode 100644 index 0000000000..9336563f12 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/installation/macos.md @@ -0,0 +1,103 @@ +--- +sidebar_position: 3 +--- + +# macOS + +:::note +Versions of macOS older than 10.12 (Sierra) are not supported. +::: + +## Installation + +- Open a terminal +- Install [Homebrew](https://brew.sh), if you don't already have it +- Add our tap: + + ```sh + brew tap evcc-io/tap + ``` + +- Update package lists l: + + ```sh + brew update + ``` + +- Install evcc: + + ```sh + brew install evcc + ``` + +- Start the evcc server: + + ```sh + brew services start evcc + ``` + +- Now check the installation by opening a browser to `http://localhost:7070`. You should see the evcc web interface in demo mode. +- Stop the evcc server: + + ```sh + brew services stop evcc + ``` + +- You can now start the configuration wizard - simply follow the prompts in your terminal! + + ```sh + evcc configure + ``` + + Once all devices are configured, you can continue on. + + :::note + Advanced users (those with evcc experience & some technical know-how) might want to use the advanced configurator: + + ```sh + evcc configure --advanced + ``` + + This mode offers some further, more technically-involved options. + ::: + +- Test to make sure your new configuration works: + + ```sh + evcc -c evcc.yaml + ``` + + Open a browser and head to `http://localhost:7070`: the evcc interface should now show your own devices. + +- If everything's working, press `CTRL+C` to stop the server. + +- Move the generated configuration to its home: + + ```sh + sudo mv evcc.yaml /etc + ``` + +- Start the evcc server: + + ```sh + brew services start evcc + ``` + +- Go back to your browser and refresh to make sure everything's working as it should be! + +## Upgrades + +To upgrade to the latest release: + +- Open a terminal +- Update package lists: + + ```sh + brew update + ``` + +- Upgrade evcc: + + ```sh + brew install evcc + ``` diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/manual.mdx b/i18n/en/docusaurus-plugin-content-docs/current/installation/manual.mdx new file mode 100644 index 0000000000..82568170e9 --- /dev/null +++ b/i18n/en/docusaurus-plugin-content-docs/current/installation/manual.mdx @@ -0,0 +1,184 @@ +--- +sidebar_position: 5 +--- + +import Tabs from "@theme/Tabs"; +import TabItem from "@theme/TabItem"; + +# Manual (including Windows) + +Manual installation requires advanced experience, especially with the terminal. + +## Installation + +- Download the latest release from [https://github.com/evcc-io/evcc/releases/latest](https://github.com/evcc-io/evcc/releases/latest) - the correct file for your system can be found below: + + + + + - 64-Bit Intel CPU: evcc_X.XX_linux_amd64.tar.gz + - 64-Bit ARM CPU: evcc_X.XX_linux_arm64.tar.gz + - 32-Bit ARM CPU (e.g. Raspberry Pi 32-Bit OS): evcc_X.XX_linux_armv6.tar.gz + + + + + - 64-Bit ARM oder Intel CPU: evcc_X.XX_macOS_all.tar.gz + + + + + - 64-Bit Intel CPU: evcc_X.XX_windows_amd64.zip + + + + +- Extract the contents to a working directory - you'll now have a `evcc` directory to work from. +- Open a terminal and change directory to `evcc`. +- You can now start the configuration wizard - simply follow the prompts in your terminal! + + ```sh + evcc configure + ``` + + Once all devices are configured, you can continue on. + + :::note + Advanced users (those with evcc experience & some technical know-how) might want to use the advanced configurator: + + ```sh + evcc configure --advanced + ``` + + This mode offers some further, more technically-involved options. + ::: + + +## Upgrades / Downgrades + +Simply download the appropriate older or newer release from our releases page, and replace the contents of your local `evcc` directory. + +## Running as a Service + +Once you've completed configuration, you can now complete your installation of evcc by creating a system service. This will ensure that evcc runs automatically when you start the system, and restarts automatically in case of an issue. + +### Linux + +:::note +This documentation presumes that your distribution uses `systemd`. +::: + +- Create a new service file: + + ```sh + sudo nano /etc/systemd/system/evcc.service + ``` + +- ... and copy the following contents into it: + + ``` + [Unit] + Description=evcc + Requires=network-online.target + After=syslog.target network.target network-online.target + Wants=network-online.target + StartLimitIntervalSec=10 + StartLimitBurst=10 + + [Service] + ExecStart=/usr/local/bin/evcc + Restart=always + RestartSec=5 + + [Install] + WantedBy=multi-user.target + ``` + + Set the appropriate path to your copy of `evcc` in `ExecStart`. + This also presumes that your `evcc.yaml` is stored at `/etc/evcc.yaml`. If that's not the case, append `-c /path/to/your/evcc.yaml` to the `ExecStart` block. + +- Load the new service, then test that it works: + + ```sh + sudo systemctl daemon-reload + sudo systemctl start evcc + sudo systemctl status evcc + ``` + + If everything's working properly, the output should include the line `Active: active (running)`. + +- Set the service to run when the system starts: + + ```sh + sudo systemctl enable evcc.service + ``` + +- You're done! 🎉 + +evcc will now run in the background as a system service. You can use the following commands to control it: + +```sh +sudo systemctl status evcc # shows status +sudo systemctl start evcc # start the service, if it isn't already running +sudo systemctl stop evcc # stops the service +sudo systemctl restart evcc # restart the service +sudo systemctl enable evcc # sets the service to run at boot +sudo systemctl disable evcc # stops the service running at boot +``` + +:::warning +If you switch to an installation of evcc controlled by a package manager (such as apt), you **must** delete the manually added service before installing the package. +:::warning + +### Windows 10 + +:::note +This documentation is very loosely translated - please feel free to contribute a better version! + +Diese Dokumentation geht davon aus, dass evcc in `c:\evcc` liegt. +::: + +- Open the start menu and search for "Task Scheduler", then right click it and choose "Run As Administrator". + +![Windows 10 Task Scheduler](win10-srv/win10-srv-1.png) + +- Once you've started Task Scheduler, you now need to choose whether to create the new service in your own folder, or in the general tasks folder. +In this example, we create the `evcc` folder. To do this, select "New Folder..." from the right hand pane. + +![Task Scheduling Library](win10-srv/win10-srv-2.png) + +- Now select the new `evcc` folder and open the popup menu again, where we now select "create task". + +![New Task window](win10-srv/win10-srv-3.png) + +- Give the task a name (probably "evcc") and a short description. Since we need to run as a system service, open user management via "Change User or Group", and enter "SYSTEM" in the box. Once you click "Check Names", the word "SYSTEM" should be underscored - you can now click OK to close this dialog. + +![Task Window](win10-srv/win10-srv-4.png) ![User Selection](win10-srv/win10-srv-5.png) + +- Select the "triggers" menu, and click "New...". +- Set the trigger to "At Startup", and check that the "activated" checkbox is ticked. + +![Trigger](win10-srv/win10-srv-6.png) + +- Open the "actions" menu, and again, select "New". +- Make sure "Start a Program" is selected, then find your `evcc.exe` executable using the Browse option. We advise also setting the path in the "Start In..." box, to make sure that the configuration file is easily found by evcc. + +![Actions](win10-srv/win10-srv-7.png) + +- Open the "conditions" menu. +- These settings should be left as default, except in one scenario: +:::info +SMA Home Manager can sometimes have issues when used with WiFi - try enabling the "Network" condition and selecting the appropriate connection interface in the dropdown. +::: + +![Conditions](win10-srv/win10-srv-8.png) + +- Open the "settings" menu. +- Make sure to select "run task as soon as possible...". +- Also make sure "Stop the task if it runs longer than:" is **not** selected, unless you want a surprise in 3 days when evcc randomly stops running. + +![Settings](win10-srv/win10-srv-9.png) + +- You're done! 🎉 + +The task can now be started manually, or test with a reboot. To check it's working as expected, use a browser to navigate to the evcc interface `http://[ipaddress]:7070`. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-1.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-1.png new file mode 100644 index 0000000000..a41de2c60e Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-1.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-2.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-2.png new file mode 100644 index 0000000000..548088d721 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-2.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-3.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-3.png new file mode 100644 index 0000000000..8aafe799e2 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-3.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-4.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-4.png new file mode 100644 index 0000000000..4fdfe74593 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-4.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-5.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-5.png new file mode 100644 index 0000000000..ed713bbdee Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-5.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-6.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-6.png new file mode 100644 index 0000000000..faa43035a4 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-6.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-7.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-7.png new file mode 100644 index 0000000000..287e4374dd Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-7.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-8.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-8.png new file mode 100644 index 0000000000..7b179c1fd5 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-8.png differ diff --git a/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-9.png b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-9.png new file mode 100644 index 0000000000..d2d60cbbc5 Binary files /dev/null and b/i18n/en/docusaurus-plugin-content-docs/current/installation/win10-srv/win10-srv-9.png differ