diff --git a/_config.yml b/_config.yml index b7a22d6845d..75a8371ae7c 100644 --- a/_config.yml +++ b/_config.yml @@ -133,7 +133,7 @@ defaults: footer: true sharing: true sidebar: true - # Enable table of contents for integrations + # Enable table of contents for integrations and installations # # To set toc as a default value, we need to set the scope with an empty path # and the collection as type @@ -144,6 +144,20 @@ defaults: type: integrations values: toc: true + - scope: + path: "installation/*" + values: + toc: true + no_toc: true + - scope: + path: "common-tasks/*" + values: + toc: true + - scope: + path: "hassio/*" + values: + toc: true + # Support for files Jekyll will normally exclude include: @@ -156,3 +170,45 @@ include: toc: min_level: 2 # default: 1 max_level: 3 # default: 6 + + +# Configuration for installation pages +installation: + versions: + os: "5.11" + python: "3.8" + types: + odroid: + board: ODROID + installation_media: "eMMC module/SD card" + variants: + - name: "ODROID-N2" + key: "odroid-n2" + - name: "ODROID-N2+" + key: "odroid-n2" + - name: "ODROID-C2" + key: "odroid-c2" + - name: "ODROID-C4" + key: "odroid-c4" + - name: "ODROID-XU4" + key: "odroid-xu4" + + raspberrypi: + board: Raspberry Pi + installation_media: "SD card" + variants: + - name: "Raspberry Pi 4 64-bit" + key: "rpi4-64" + - name: "Raspberry Pi 4 32-bit" + key: "rpi4" + - name: "Raspberry Pi 3 64-bit" + key: "rpi3-64" + - name: "Raspberry Pi 3 32-bit" + key: "rpi" + + tinkerboard: + board: ASUS Tinkerboard + installation_media: "eMMC module/SD card" + variants: + - name: "ASUS Tinkerboard" + key: "tinker" diff --git a/plugins/tabbed_block.rb b/plugins/tabbed_block.rb new file mode 100644 index 00000000000..508dbf54940 --- /dev/null +++ b/plugins/tabbed_block.rb @@ -0,0 +1,63 @@ +require 'securerandom' + +module Jekyll + class TabbedBlock < Liquid::Block + + def slug(key) + key.downcase.strip.gsub(' ', '-').gsub(/[^\w\-]/, '') + end + + def render_tabbed_block(vars:, converter:, classes: nil, parent_type: nil) + block = Array.new + tabs = Array.new + tabContent = Array.new + uuid = "id" + SecureRandom.hex(10) + + tabs << "
" + vars.map do |entry| + tabs << "" + tabContent << "
#{converter.convert(entry['content'].to_s)}
" + end + tabs << "
" + block << tabs.join + block << tabContent.join + block.join + end + + def render(context) + contents = super(context) + vars = SafeYAML.load(contents) + + site = context.registers[:site] + converter = site.find_converter_instance(::Jekyll::Converters::Markdown) + + <<~MARKUP + +
+ #{render_tabbed_block(vars: vars, converter: converter)} +
+ MARKUP + end + end +end + +Liquid::Template.register_tag('tabbed_block', Jekyll::TabbedBlock) \ No newline at end of file diff --git a/sass/custom/_getting_started.scss b/sass/custom/_getting_started.scss new file mode 100644 index 00000000000..9cab303af76 --- /dev/null +++ b/sass/custom/_getting_started.scss @@ -0,0 +1,150 @@ +#getting_started { + .intro { + padding-bottom: 16px; + } + + .installations { + + h2 { + font-size: 0; + margin: 0; + } + + .installations-card { + text-decoration: none !important; + color: black !important; + + .material-card { + display: flex; + flex-direction: row; + justify-content: space-between; + margin: 8px 0; + + .content-container { + display: flex; + + div:first-of-type { + margin-right: 24px; + + img, svg { + max-width: 170px; + max-height: 170px; + min-width: 170px; + min-height: 170px; + padding: 32px; + border-radius: 3px; + box-shadow: rgba(0,0,0,0.06) 0 0 10px; + vertical-align: middle; + border: 5px solid #fff; + } + } + + div:last-of-type { + + b { + font-size: 28px; + } + + p { + font-size: 0.8em; + margin: 0; + } + + ul { + font-size: 0.8em; + margin-left: 24px; + margin-top: 1rem; + + li { + margin: 0; + } + } + } + } + svg { + height: 42px; + max-width: 42px; + min-width: 42px; + align-self: center; + } + } + } + } + + .compare-installations td,.compare-installations th { + text-align: center; + } + + table.compare-installations { + background-color: #ffffff !important; + border-radius: 2px !important; + box-shadow: 0 2px 2px 0 rgba(0,0,0,0.14), + 0 1px 5px 0 rgba(0,0,0,0.12), + 0 3px 1px -2px rgba(0,0,0,0.2) !important; + + td, th { + text-align: center; + } + + tr { + td:first-of-type { + text-align: left; + } + } + + tr:nth-child(even) { + background-color: #fafafa; + } + } +} + +.link-card { + text-decoration: none !important; + color: black !important; + div { + margin: 32px 0; + height: 64px; + display: flex; + justify-content: space-between; + svg { + height: 32px; + width: 32px; + max-width: 32px; + } + p { + margin: 0; + align-self: center; + } + } +} +.next-step { + p { + text-transform: uppercase; + } +} + +@media only screen and (max-width: $palm-end) { + #getting_started { + .installations { + .installations-card { + .material-card { + .content-container { + flex-flow: wrap; + svg { + display: block; + } + div:first-of-type { + width: 100%; + display: flex; + justify-content: center; + margin-bottom: 16px; + } + } + svg { + display: none; + } + } + } + } + } +} \ No newline at end of file diff --git a/sass/custom/_tabbed_block.scss b/sass/custom/_tabbed_block.scss new file mode 100644 index 00000000000..818276e63f3 --- /dev/null +++ b/sass/custom/_tabbed_block.scss @@ -0,0 +1,48 @@ +.tabbed-content-block { + background-color: #FAFAFA; + margin: 16px 0; + overflow: hidden; + border-radius: 10px; + box-shadow: -1px 0px 0px 0px #dfdfdf, 0px 0px 0px 1px #dfdfdf; + box-sizing: border-box; + + .tabbed-content-block-tabs { + overflow: hidden; + padding: 0 8px; + + label { + input{ + display:none; + } + input:checked + div{ + opacity: 1; + border-bottom: 2px solid $primary-color; + } + + div{ + float:left; + padding: 8px; + cursor: pointer; + opacity: 0.7; + transition: 0.3s; + border-bottom: 2px solid transparent; + font-size: 0.8em; + } + + div:hover { + opacity: 1; + } + } + } + + .tabbed-content-block-content { + padding: 8px 16px 0; + display: none; + animation: fadeEffect .5s; + } + + @keyframes fadeEffect{ + 0%{opacity:0} + 100%{opacity:1} + } +} \ No newline at end of file diff --git a/sass/screen.scss b/sass/screen.scss index dda71c2daa4..13ef2c23179 100644 --- a/sass/screen.scss +++ b/sass/screen.scss @@ -6,4 +6,6 @@ @import 'custom/syntax'; @import 'custom/details'; @import 'custom/print'; -@import 'custom/layout'; \ No newline at end of file +@import 'custom/layout'; +@import 'custom/getting_started'; +@import 'custom/tabbed_block'; \ No newline at end of file diff --git a/source/_docs/installation.markdown b/source/_docs/installation.markdown deleted file mode 100644 index 8ba3c999d4b..00000000000 --- a/source/_docs/installation.markdown +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Installation of Home Assistant" -description: "Instructions on how to install Home Assistant to launch on start." ---- - -
- -Beginners should check our [Getting started guide](/getting-started/) first. - -
- -Home Assistant provides multiple ways to be installed. The first start may take up to 20 minutes because the required packages will be downloaded and installed. The web interface will be served on `http://ip.add.re.ss:8123/`. Replace `ip.add.re.ss` with the IP of the computer you installed it on. - -
- - Please remember to [secure your installation](/docs/configuration/securing/) once you've finished with the installation process. - -
- -## Hardware - -Below is a list of **minimum** requirements - -Type | Minimum --- | -- -Storage | 32 GB -Memory | 1 GB -Network | 100 Mb/s wired -Power (if Pi) | At least 2.5A - -### Performance expectations - -This is a list of popular platforms and what to expect from them. - -Platform | Notes --- | -- -Raspberry Pi Zero/Pi 2 | **Only** use these for testing -Raspberry Pi 3/3+/4 | This is a good starting point, and depending on the amount of devices you integrate this can be enough - use an [A2 class SD](https://amzn.to/2X0Z2di) card if possible. -NUC i3 | This is if you need a little more power over a Pi -NUC i5 | This will allow you to run multiple services without any issues, perfect for a homelab -NUC i7/i9 | Pure power, you should not have *any* performance issues - -## Recommended - -These install options are fully supported by Home Assistant's documentation. For example, if an integration requires that you install something to make it work on one of these methods then the integration page will document the steps required. - -
- -The only installation methods that allow you to use Home Assistant Add-ons is using the Home Assistant image. All other methods only install the base Home Assistant packages, however the software from the add-ons may still usually be installed manually like any other program. - -
- -**Method**|**You have**|**Recommended for** -:-----|:-----|:----- -[Home Assistant OS](/hassio/installation/)|[A supported platform](/hassio/installation/)|Anybody -[Home Assistant Container](/docs/installation/docker/)|Docker|Anybody already running Docker - -## Alternative installs - -If you use these install methods, we assume that you know how to manage and administer the operating system you're using. Due to the range of platforms on which these install methods can be used, integration documentation may only tell you what you have to install, not how to install it. - -**Method**|**You have**|**Recommended for** -:-----|:-----|:----- -[Home Assistant Core](/docs/installation/raspberry-pi/)|Any Linux, Python 3.8 or later|Those familiar with their operating system -[Home Assistant Supervised](https://github.com/home-assistant/supervised-installer) | [Requirements](https://github.com/home-assistant/architecture/blob/master/adr/0014-home-assistant-supervised.md#supported-operating-system-system-dependencies-and-versions) | Those very familiar with their operating system -[venv
(as your user)](/docs/installation/virtualenv/)|Any Python 3.8 or later|**Developers** - -## Community provided guides - -Additional installation guides can be found on our [Community Forum](https://community.home-assistant.io/tags/c/community-guides/51/installation). - -These Community Guides are provided as-is. Some of these install methods are more limited than the methods above. Some integrations may not work due to limitations of the platform. diff --git a/source/_docs/installation/docker.markdown b/source/_docs/installation/docker.markdown deleted file mode 100644 index b92b6a7f736..00000000000 --- a/source/_docs/installation/docker.markdown +++ /dev/null @@ -1,317 +0,0 @@ ---- -title: "Installation on Docker" -description: "Instructions to install Home Assistant on a Docker." ---- - -
- -These below instructions are for an installation of Home Assistant Core running in your own Docker environment, which you manage yourself. - -Note that Docker command line option `--net=host` or the compose file equivalent `network_mode: host` must be used to put Home Assistant on the host's network, otherwise certain functionality - including mDNS and UPnP - will break. The `-p` command line option or the compose file equivalent `ports:` is not compatible with host networking mode and must not be used. - -
- -## Platform Installation - -Installation with Docker is straightforward. Adjust the following command so that `/PATH_TO_YOUR_CONFIG` points at the folder where you want to store your configuration and run it: - -## Autostart using Docker - -
- -Do not try to combine Docker `restart` policies with host-level process managers (such as `systemd`), because this creates conflicts. - -
- -Add `--restart=always` to your `docker run` command before homeassistant/home-assistant:stable. See [the Docker autostart documentation](https://docs.docker.com/config/containers/start-containers-automatically/) for details and more options. - -### Linux - -```bash -docker run -d --name="home-assistant" -v /PATH_TO_YOUR_CONFIG:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant:stable -``` - -Updating: - -```bash -docker pull homeassistant/home-assistant:stable # if this returns "Image is up to date" then you can stop here -docker stop home-assistant # stop the running container -docker rm home-assistant # remove it from Docker's list of containers -docker run -d --name="home-assistant" -v /PATH_TO_YOUR_CONFIG:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant:stable # finally, start a new one -``` - -### Raspberry Pi 3/4 (Raspberry Pi OS) - -Raspberry Pi 3: -```bash -docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/raspberrypi3-homeassistant:stable -``` - -Raspberry Pi 4: -```bash -docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/raspberrypi4-homeassistant:stable -``` - -You need to replace `/PATH_TO_YOUR_CONFIG` with your path to the configuration. For example, if you choose your configuration path to be `/home/pi/homeassistant`, the command for **Raspberry Pi 3** would be: - -```bash -docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /home/pi/homeassistant:/config --net=host homeassistant/raspberrypi3-homeassistant:stable -``` - -### macOS - -When using `docker-ce` (or `boot2docker`) on macOS, you are unable to map the local timezone to your Docker container ([Docker issue](https://github.com/docker/for-mac/issues/44)). Instead of `-v /etc/localtime:/etc/localtime:ro`, just pass in the timezone environment variable when you launch the container, e.g, `-e "TZ=America/Los_Angeles"`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones). - -```bash -docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config -p 8123:8123 homeassistant/home-assistant:stable -``` - -Alternatively, `docker-compose` works with any recent release of Docker CE on macOS. Note the `/dev/tty*` device name used by your Arduino etc. devices will differ from the Linux example, so the compose `mount:` may require updates. - -### Windows - -Docker containers are completely isolated from its Windows host system. So when you delete a container, all the changes you made to that container are also removed. If you want to have configuration files or other assets remain persistent, try mounting Windows folders on containers. - -Before proceeding, make sure you have shared out a drive for Docker to mount to. This will allow the saving of configuration files to persist on the local machine rather than in the Docker container (which may be destroyed when upgraded). - - - - -```powershell -docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config -p 8123:8123 homeassistant/home-assistant:stable -``` - -It’s easier to understand the trick when put into practice. Here we would like to mount a current working directory (something like `C:\Users\\homeassistant` make sure this exists first) into the `homeassistant/home-assistant:stable` image at the `/config` location in the container. We would do that as so: - -```powershell -docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v //c/Users//homeassistant:/config -p 8123:8123 homeassistant/home-assistant:stable -``` - -Host networking is not supported on Windows so we have to forward the port 8123. This will let you access your Home Assistant portal from `http://localhost:8123`, and if you forward port 8123 on your router to your machine IP, the traffic will be forwarded on through to the Docker container. - -### Synology NAS - -As Synology within DSM now supports Docker (with a neat UI), you can simply install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see - -The steps would be: - -- Install "Docker" package on your Synology NAS -- Launch Docker-app and move to "Registry"-section -- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "stable" tag. -- Wait for some time until your NAS has pulled the image -- Move to the "Image"-section of the Docker-app -- Click on "Launch" -- Choose a container-name you want (e.g., "homeassistant") -- Click on "Advanced Settings" -- Set "Enable auto-restart" if you like -- Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount path" has to be "/config", so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named "config" or "homeassistant/config" to avoid confusion when referencing it within service calls. -- Within "Network" select "Use same network as Docker Host" -- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) -- Confirm the "Advanced Settings" -- Click on "Next" and then "Apply" -- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`) - -If you are using the built-in firewall, you must also add the port 8123 to allowed list. This can be found in "Control Panel -> Security" and then the Firewall tab. Click "Edit Rules" besides the Firewall Profile dropdown box. Create a new rule and select "Custom" for Ports and add 8123. Edit Source IP if you like or leave it at default "All". Action should stay at "Allow". - -To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS: - - - -See this page for accessing the Terminal via SSH: - - - -Adjust the following Terminal command as follows : - -- Replace `/PATH_TO_YOUR_CONFIG` points at the folder where you want to store your configuration -- Replace `/PATH_TO_YOUR_USB_STICK` matches the path for your USB stick (e.g., `/dev/ttyACM0` for most Synology users) -- Replace "Australia/Melbourne" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - -Run it in Terminal. - -```bash -sudo docker run --restart always -d --name="homeassistant" -v /PATH_TO_YOUR_CONFIG:/config --device=/PATH_TO_YOUR_USB_STICK -e TZ=Australia/Melbourne --net=host homeassistant/home-assistant:stable -``` - -Complete the remainder of the Z-Wave configuration by [following the instructions here.](/docs/z-wave/installation) - -Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following: - -- Go to the Docker-app and move to "Registry"-section -- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "stable" tag. -- Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar) -- Move to "Container"-section -- Stop your container if it's running -- Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your configuration-directory -- Start the container again - it will then boot up with the new Home Assistant image - -Remark: to restart your Home Assistant within Synology NAS, you just have to do the following: - -- Go to the Docker-app and move to "Container"-section -- Right-click on it and select "Action"->"Restart". - -
- -If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assistant on Synology Docker these instructions do not correctly configure the container to access the USB devices. To configure these devices on your Synology Docker Home Assistant you can follow the instructions provided [here](https://philhawthorne.com/installing-home-assistant-io-on-a-synology-diskstation-nas/) by Phil Hawthorne. - -
- -### QNAP NAS - -As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see - -The steps would be: - -- Install "Container Station" package on your Qnap NAS -- Launch Container Station and move to "Create Container"-section -- Search image "homeassistant/home-assistant" with Docker Hub and click on "Install" - Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is "homeassistant/armhf-homeassistant" -- Choose "stable" version and click next -- Choose a container-name you want (e.g., "homeassistant") -- Click on "Advanced Settings" -- Within "Shared Folders" click on "Volume from host" > "Add" and choose either an existing folder or add a new folder. The "mount point has to be `/config`, so that Home Assistant will use it for the configuration and logs. -- Within "Network" and select Network Mode to "Host" -- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) -- Click on "Create" -- Wait for some time until your NAS has created the container -- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example `http://192.xxx.xxx.xxx:8123`) - -Remark: To update your Home Assistant on your Docker within Qnap NAS, you just remove container and image and do steps again (Don't remove "config" folder). - -If you want to use a USB Bluetooth adapter or Z-Wave USB stick with Home Assistant on Qnap Docker, follow those steps: - -#### Z-Wave - -- Connect to your NAS over SSH -- Load cdc-acm kernel module(when NAS restart need to run this command) - `insmod /usr/local/modules/cdc-acm.ko` -- Find USB devices attached. Type command: - `ls /dev/tty*` - The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. Like : `ttyACM0` - -- Run Docker command: - - ```bash - docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e TZ=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable - ``` - - `-v` is your configuration path - `-e` is set timezone - -- Edit `configuration.yaml` - -```yaml -zwave: - usb_path: /dev/ttyACM0 -``` - -That will tell Home Assistant where to look for our Z-Wave radio. - -#### Bluetooth - -- Connect to your NAS over SSH -- Run Docker command: - - ```bash - docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e TZ=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable - ``` - - First `-v` is your configuration path - `-e` is set timezone - -- Edit the `configuration.yaml` file - -```yaml -device_tracker: - - platform: bluetooth_tracker -``` - -## Restart - -If you change the configuration you have to restart the server. To do that you have 2 options. - - 1. You can go to the **Developer Tools** -> **Services**, select the service `homeassistant.restart` and click "Call Service". - 2. Or you can restart it from a terminal by running `docker restart home-assistant` - -## Docker Compose - -As the Docker command becomes more complex, switching to `docker-compose` can be preferable and support automatically restarting on failure or system restart. Create a `docker-compose.yml` file: - -```yaml - version: "3" - services: - homeassistant: - container_name: home-assistant - image: homeassistant/home-assistant:stable - volumes: - - /PATH_TO_YOUR_CONFIG:/config - environment: - - TZ=America/New_York - restart: always - network_mode: host -``` - -Then start the container with: - -```bash -docker-compose up -d -``` - -To restart Home Assistant when you have changed configuration: - -```bash -docker-compose restart -``` - -To update your docker-compose image to the latest version and restart: - -```bash -docker-compose pull homeassistant -docker-compose up -d -``` - -Note: the above will fetch the latest matching image for the `homeassistant` service only. To fetch all matching images for all services defined in the same `docker-compose.yaml` file, omit the service name from the first command. - -## Exposing Devices - -In order to use Z-Wave, Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the `/dev/tty*` file, then add the device mapping to your Docker command: - -```bash -$ docker run --init -d --name="home-assistant" -v /PATH_TO_YOUR_CONFIG:/config \ - -e "TZ=Australia/Melbourne" --device /dev/ttyUSB0:/dev/ttyUSB0 \ - --net=host homeassistant/home-assistant:stable -``` - -or in a `docker-compose.yml` file: - -```yaml - version: "3" - services: - homeassistant: - container_name: home-assistant - image: homeassistant/home-assistant:stable - volumes: - - /PATH_TO_YOUR_CONFIG:/config - devices: - - /dev/ttyUSB0:/dev/ttyUSB0 - - /dev/ttyUSB1:/dev/ttyUSB1 - - /dev/ttyACM0:/dev/ttyACM0 - environment: - - TZ=America/New_York - restart: always - network_mode: host -``` - -
- -On Mac, USB devices are [not passed through](https://github.com/docker/for-mac/issues/900) by default. Follow the instructions in [Using USB with Docker for Mac](https://dev.to/rubberduck/using-usb-with-docker-for-mac-3fdd) by Christopher McClellan if your device is not showing up. - -
- -## Optimizations - -The Home Assistant Container is using an alternative memory allocation library [jemalloc](http://jemalloc.net/) for better memory management and Python runtime speedup. - -As jemalloc can cause issues on certain hardware, it can be disabled by passing the environment variable `DISABLE_JEMALLOC` with any value, for example: `-e "DISABLE_JEMALLOC=true"`. - -The error message `: Unsupported system page size` is one known indicator. diff --git a/source/_docs/installation/raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown deleted file mode 100644 index 1c6cef6a41d..00000000000 --- a/source/_docs/installation/raspberry-pi.markdown +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: "Manual installation on a Raspberry Pi" -description: "Instructions to install Home Assistant Core on a Raspberry Pi running Raspberry Pi OS Lite." ---- - -This installation of Home Assistant Core requires the Raspberry Pi to run [Raspberry Pi OS Lite](https://www.raspberrypi.org/downloads/raspberry-pi-os/). The installation will be installed in a [Virtual Environment](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspberry Pi OS Lite. - -You must have Python 3.8 or later installed (including the package `python3-dev`) which is *not* the case for Raspberry Pi OS and you will need to install Python manually. - -
-Although these installation steps specifically mention a Raspberry Pi, you can go ahead and proceed on any Linux install as well. This guide is also referred to as the "Advanced Guide" for a virtual environment install. -
- -
- -Please remember to ensure you're using an [appropriate power supply](https://www.raspberrypi.org/documentation/faqs/#pi-power) with your Pi. Mobile chargers may not be suitable, since some are designed to only provide the full power with that manufacturer's handsets. USB ports on your computer also will not supply enough power and must not be used. - -
- -Connect to the Raspberry Pi over SSH. Default password is `raspberry`. -You will need to enable SSH access. The Raspberry Pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/). - -```bash -ssh pi@ipaddress -``` - -Changing the default password is encouraged. - -```bash -passwd -``` - -Update the system. - -```bash -sudo apt-get update -sudo apt-get upgrade -y -``` - -Install the dependencies. - -```bash -sudo apt-get install python3 python3-dev python3-venv python3-pip libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff5 -``` - -Add an account for Home Assistant Core called `homeassistant`. -Since this account is only for running Home Assistant Core the extra arguments of `-rm` is added to create a system account and create a home directory. The arguments `-G dialout,gpio,i2c` adds the user to the `dialout`, `gpio` and the `i2c` group. The first is required for using Z-Wave and Zigbee controllers, while the second is required to communicate with Raspberry's GPIO. - -```bash -sudo useradd -rm homeassistant -G dialout,gpio,i2c -``` - -Next we will create a directory for the installation of Home Assistant Core and change the owner to the `homeassistant` account. - -```bash -cd /srv -sudo mkdir homeassistant -sudo chown homeassistant:homeassistant homeassistant -``` - -Next up is to create and change to a virtual environment for Home Assistant Core. This will be done as the `homeassistant` account. - -```bash -sudo -u homeassistant -H -s -cd /srv/homeassistant -python3.8 -m venv . -source bin/activate -``` - -Once you have activated the virtual environment (notice the prompt change to `(homeassistant) homeassistant@raspberrypi:/srv/homeassistant $`) you will need to run the following command to install a required Python package. - -```bash -python3 -m pip install wheel -``` - -Once you have installed the required Python package it is now time to install Home Assistant Core! - -```bash -pip3 install homeassistant -``` - -Start Home Assistant Core for the first time. This will complete the installation for you, automatically creating the `.homeassistant` configuration directory in the `/home/homeassistant` directory, and installing any basic dependencies. - -```bash -hass -``` - -You can now reach your installation on your Raspberry Pi over the web interface on `http://ipaddress:8123`. - -
- -When you run the `hass` command for the first time, it will download, install and cache the necessary libraries/dependencies. This procedure may take anywhere between 5 to 10 minutes. During that time, you may get "site cannot be reached" error when accessing the web interface. This will only happen for the first time, and subsequent restarts will be much faster. - -
- -## Updating - -To update to the latest version of Home Assistant Core follow these simple steps: - -```bash -sudo -u homeassistant -H -s -source /srv/homeassistant/bin/activate -pip3 install --upgrade homeassistant -``` - -Once the last command executes, restart the Home Assistant Core service to apply the latest updates. Please keep in mind that some updates may take longer to start up than others. If Home Assistant Core fails to start, make sure you check the **Breaking Changes** from the [Release Notes](https://www.home-assistant.io/latest-release-notes/). - -## Run a specific version - -In the event that a Home Assistant Core version doesn't play well with your hardware setup, you can downgrade to a previous release. For example: - -```bash -sudo -u homeassistant -H -s -source /srv/homeassistant/bin/activate -pip3 install homeassistant==0.XX.X -``` - -## Run the beta version - -If you would like to test next release before anyone else, you can install the beta version released every two weeks, for example: - -```bash -sudo -u homeassistant -H -s -source /srv/homeassistant/bin/activate -pip3 install --pre --upgrade homeassistant -``` - -## Run the development version - -If you want to stay on the bleeding-edge Home Assistant Core development branch, you can upgrade to `dev`. - -
- The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption. -
- -For example: - -```bash -sudo -u homeassistant -H -s -source /srv/homeassistant/bin/activate -pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev -``` - -## Activating the virtual environment - -When instructions tell you to activate the virtual environment, the following commands will do this: - -```bash -sudo -u homeassistant -H -s -source /srv/homeassistant/bin/activate -``` diff --git a/source/_docs/installation/updating.markdown b/source/_docs/installation/updating.markdown deleted file mode 100644 index 5352fdbc3ea..00000000000 --- a/source/_docs/installation/updating.markdown +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "Updating Home Assistant" -description: "Step to update Home Assistant." ---- - -
- -The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install: [Home Assistant](/hassio/) or [Home Assistant Core](/docs/installation/virtualenv/#upgrade). - -
- -Check what's new in the latest version and potentially impacts your system in the [Home Assistant release notes](https://github.com/home-assistant/home-assistant/releases). It is good practice to review these release notes and pay close attention to the **Breaking Changes** that are listed there. If you haven't done an update for a while, you should also check previous release notes as they can also contain relevant **Breaking Changes**. These **Breaking Changes** may require configuration updates for your components. If you missed this and Home Assistant refuses to start, check the log file in the [configuration](/docs/configuration/) directory, e.g., `.homeassistant/home-assistant.log`, for details about broken components. - -
- -To avoid permission errors, the upgrade must be run as the same user as was used during the initial installation, again review the documentation specific to your install [Home Assistant](/hassio/) or [Home Assistant Core](/docs/installation/virtualenv). - -
- -The default way to update Home Assistant to the latest release, when available, is: - -```bash -pip3 install --upgrade homeassistant -``` - -For a Docker container, simply pull the latest stable one: - -```bash -sudo docker pull homeassistant/home-assistant:stable -``` - -For a Raspberry Pi Docker container, simply pull the latest stable one: - -```bash -sudo docker pull homeassistant/raspberrypi3-homeassistant:stable -``` - -After updating, you must start/restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself. -Startup can take a considerable amount of time (i.e., minutes) depending on your device. This is because all requirements are updated as well. - -[BRUH automation](https://www.bruhautomation.io/) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant. - -## Run a specific version - -In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release: - -```bash -pip3 install homeassistant==0.XX.X -``` - -## Run the beta version - -If you would like to test the next release before anyone else, you can install the beta version released every two weeks: - -```bash -pip3 install --pre --upgrade homeassistant -``` - -## Run the development version - -If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to `dev`. - -
- The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption. -
- -```bash -pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev -``` - -## Update Home Assistant installation - -Best practice for updating a Home Assistant installation: - -1. Backup your installation, using the snapshot functionality Home Assistant offers. -2. Check the release notes for breaking changes on [Home Assistant release notes](https://github.com/home-assistant/home-assistant/releases). Be sure to check all release notes between the version you are running and the one you are upgrading to. Use the search function in your browser (`CTRL + f`) and search for **Breaking Changes**. -3. Check your configuration using the [Check Home Assistant configuration](/addons/check_config/) add-on. -4. If the check passes, you can safely update. If not, update your configuration accordingly. -5. Update Home Assistant. diff --git a/source/_docs/installation/virtualenv.markdown b/source/_docs/installation/virtualenv.markdown deleted file mode 100644 index 3676ecf1b26..00000000000 --- a/source/_docs/installation/virtualenv.markdown +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Installation in Python virtual environment" -description: "How to install Home Assistant in a Python virtual environment." ---- - -If you already have Python 3.8 or later installed, you can easily give Home Assistant a spin. - -It's recommended when installing Python packages that you use a [virtual environment](https://docs.python.org/3.8/library/venv.html#module-venv). This will make sure that your Python installation and Home Assistant installation won't impact one another. The following steps will work on most UNIX like systems. - -
- -This is a generic guide for running Home Assistant under Python. We recommend to use [our recommended installation guides](/docs/installation/#recommended). The steps below may be shorter but some users find difficulty when applying updates and may run into issues. - -Before you begin the guide below, ensure that you have a *so-called standard* build environment that includes things like `make`, `gcc`, `python3`, including Python 3 `setuptools` and `pip` modules. Less obvious is the need to install `libssl-dev` (for opensslv.h), `libffi-dev` (for cffi.h) for things to build later on, `libjpeg-dev`, `zlib1g-dev`, `libopenjp2-7` and `libtiff5` needed for the frontend. - -
- -{% comment %} -This page describes installation instructions for a pure Python installation. -It should not contain any OS specific instructions. -{% endcomment %} - -### Install - - 1. Create a virtual environment in your current directory: - ```bash - python3.8 -m venv homeassistant - ``` - 2. Open the virtual environment: - ```bash - cd homeassistant - ``` - 3. Activate the virtual environment: - ```bash - source bin/activate - ``` - 4. Install Home Assistant: - ```bash - python3 -m pip install homeassistant - ``` - 5. Run Home Assistant: - ```bash - hass --open-ui - ``` - 6. You can now reach the web interface on `http://ipaddress:8123/` - the first start may take a couple of minutes before the web interface is available. This can take longer if you're using lower-end hardware like a Raspberry Pi Zero. - -### Upgrade - - 1. Stop Home Assistant - - 2. Open the directory where the virtual environment is located, activate the virtual environment, then upgrade Home Assistant: - ```bash - cd homeassistant - source bin/activate - python3 -m pip install --upgrade homeassistant - ``` - 3. Start Home Assistant - 4. You can now reach the web interface on `http://ipaddress:8123/` - the first start may take some time before the web interface is available, depending on how many integrations need to be upgraded. - -### Run a specific version - -In the event that a Home Assistant version doesn't play well with your hardware setup, you can downgrade to a previous release. For example: - -```bash -cd homeassistant -source bin/activate -pip3 install homeassistant==0.XX.X -``` - -#### Run the beta version - -If you would like to test next release before anyone else, you can install the beta version, for example: - -```bash -cd homeassistant -source bin/activate -pip3 install --pre --upgrade homeassistant -``` - -#### Run the development version - -If you want to stay on the bleeding-edge Home Assistant development branch, you can upgrade to `dev`. - -
- The "dev" branch is likely to be unstable. Potential consequences include loss of data and instance corruption. -
- -For example: - -```bash -cd homeassistant -source bin/activate -pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev -``` - -### Notes - -- In the future, if you want to start Home Assistant manually again, follow step 2, 3 and 5. -- It's recommended to run Home Assistant as a dedicated user. - -
- -Looking for more advanced guides? Check our [Raspberry Pi OS guide](/docs/installation/raspberry-pi/) or the [other installation guides](/docs/installation/). - -
- -### After upgrading Python - -If you've upgraded Python (for example, you were running 3.8.1 and now you've installed 3.8.6) then you'll need to build a new virtual environment. Simply rename your existing virtual environment directory: - -```bash -mv homeassistant homeassistant.old -``` - -Then follow the [Install](#install) steps again, being sure to use the newly installed version of Python. diff --git a/source/_docs/installation/troubleshooting.markdown b/source/_docs/troubleshooting.markdown similarity index 97% rename from source/_docs/installation/troubleshooting.markdown rename to source/_docs/troubleshooting.markdown index 991ab732d6c..a6a0d70ec53 100644 --- a/source/_docs/installation/troubleshooting.markdown +++ b/source/_docs/troubleshooting.markdown @@ -46,7 +46,7 @@ iptables-save > /etc/network/iptables.rules # your rules may be saved elsewhere ### System freezes -On small systems (such as a Pi2), not directly sypported by binaries (Python Wheels) you may run out of memory. +On small systems (such as a Pi2), not directly supported by binaries (Python Wheels) you may run out of memory. Upon the first run or after an upgrade, Home Assistant uses a lot of resources to (re)compile all the integrations. If you run out of memory and/or swap memory, your system will freeze. Increasing swap memory can help: diff --git a/source/_faq/404.markdown b/source/_faq/404.markdown new file mode 100644 index 00000000000..9d141de0354 --- /dev/null +++ b/source/_faq/404.markdown @@ -0,0 +1,13 @@ +--- +title: "404 Client Error: Not Found ('no such image: homeassistant/...)" +ha_category: Home Assistant +--- + +This error indicates the image, whether for updating to Home Assistant or installing or updating an add-on, was not able to be pulled to your system. This is usually a situation where there is not enough space for the image to be downloaded. The first thing to check for is the available space on your system. + +Please note, if you are running the operating system as a virtual machine; the default VM image is only about 6GB. Many VM users run into this as they have not allocated enough storage. 32GB is the minimum recommended size. + +You will need to explore your own system to determine where space has gone. +Using `df -h` in the SSH add-on console to you can quickly check to see if you have space available. + +If there is plenty of space available then you might check to see if you are having network issues that are preventing images from being downloaded. \ No newline at end of file diff --git a/source/_faq/addon_not_starting.markdown b/source/_faq/addon_not_starting.markdown new file mode 100644 index 00000000000..296490979c1 --- /dev/null +++ b/source/_faq/addon_not_starting.markdown @@ -0,0 +1,8 @@ +--- +title: "Why does the start button for an add-on flash red when I click it?" +ha_category: Home Assistant +--- + +If you are looking for more information about add-ons, which won't start or install, navigate to Supervisor > System in the UI and check the logs. + +The logs on this page are the same you would see using `ha logs` in the custom CLI. diff --git a/source/_faq/rpi4_8gb.markdown b/source/_faq/rpi4_8gb.markdown new file mode 100644 index 00000000000..1be74dc1bf4 --- /dev/null +++ b/source/_faq/rpi4_8gb.markdown @@ -0,0 +1,6 @@ +--- +title: "Is the Raspberry Pi 4 with 8GB RAM supported?" +ha_category: Home Assistant +--- + +The Raspberry Pi 4 with 8GB RAM is supported with Home Assistant OS 5.5 and later using the 32-bit and 64-bit image. The 64-bit is the better tested option at this point. \ No newline at end of file diff --git a/source/_faq/sdcard_files.markdown b/source/_faq/sdcard_files.markdown new file mode 100644 index 00000000000..6004145dc7f --- /dev/null +++ b/source/_faq/sdcard_files.markdown @@ -0,0 +1,9 @@ +--- +title: "I'm trying to find my files on the host or SD card. Where are they?" +ha_category: Home Assistant +--- + +On a Home Assistant OS install, your files are on the data partition within `/mnt/data/supervisor/`. +On the SD itself, this is an EXT4 partition labeled `hassos-data`. + +On a Supervised install, they are in `/usr/share/hassio/`. \ No newline at end of file diff --git a/source/_faq/usb_boot.markdown b/source/_faq/usb_boot.markdown new file mode 100644 index 00000000000..9b7dc3f364f --- /dev/null +++ b/source/_faq/usb_boot.markdown @@ -0,0 +1,8 @@ +--- +title: "Is USB Boot for the Raspberry Pi 4 supported?" +ha_category: Home Assistant +--- + +Due to the complexity of USB and the USB mass storage device class booting from a USB device is brittle. Since booting from a USB drive this process has to be done multiple times (firmware/boot loader and the operating system), there is a high chance that this process doesn't complete in one of these stages. In general, the Linux USB stack is solid. Due to this, it is recommended to boot Home Assistant OS from an SD card and use a USB attached flash drive as data partition only. The `datactl` command, available on the OS shell, allows moving of the data partition. + +That said, booting Home Assistant OS completely from a USB drive (SSD or any other USB mass storage device) works with *some* USB devices. USB Devices that are known to work with Raspberry Pi OS (check the Raspberry Pi Forum) are more likely to work with Home Assistant OS. However, because Home Assistant OS has also U-Boot in the boot chain, there are devices which are known to work with Raspberry Pi OS but do *not* work with Home Assistant OS. \ No newline at end of file diff --git a/source/_faq/usb_config.markdown b/source/_faq/usb_config.markdown new file mode 100644 index 00000000000..a3d100a6d77 --- /dev/null +++ b/source/_faq/usb_config.markdown @@ -0,0 +1,6 @@ +--- +title: "Do I need to leave the USB stick connected for Wi-Fi?" +ha_category: Home Assistant +--- + +No. The USB "CONFIG" stick is only used to import a network profile to `/etc/NetworkManager/system-connections/` and can be removed. \ No newline at end of file diff --git a/source/_includes/asides/common_tasks_navigation.html b/source/_includes/asides/common_tasks_navigation.html new file mode 100644 index 00000000000..92eb027cb99 --- /dev/null +++ b/source/_includes/asides/common_tasks_navigation.html @@ -0,0 +1,11 @@ +
+
+

Common Tasks

+
    +
  • {% active_link /common-tasks/os/ Home Assistant Operating System %}
    • +
  • {% active_link /common-tasks/container/ Home Assistant Container %}
    • +
  • {% active_link /common-tasks/core/ Home Assistant Core %}
    • +
  • {% active_link /common-tasks/supervised/ Home Assistant Supervised %}
    • +
+
+
diff --git a/source/_includes/asides/component_navigation.html b/source/_includes/asides/component_navigation.html index a5e54266097..01975079f1e 100644 --- a/source/_includes/asides/component_navigation.html +++ b/source/_includes/asides/component_navigation.html @@ -67,11 +67,6 @@ {%- endif -%} - {%- unless page.no_toc -%} -
-

On this page

- {% toc %} - {%- endunless -%} diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index f70674aa17c..06730186efb 100644 --- a/source/_includes/asides/docs_navigation.html +++ b/source/_includes/asides/docs_navigation.html @@ -8,12 +8,12 @@ {% active_link /docs/glossary/ Glossary %}
  • - {% active_link /docs/installation/ Installation %} + {% active_link /getting-started Getting Started %}
      -
    • {% active_link /hassio/ Home Assistant %}
      • -
    • {% active_link /docs/installation/updating/ Updating %}
      • +
    • {% active_link /installation Installation %}
      • +
    • {% active_link /common-tasks/os/ Common Tasks %}
    • - {% active_link /docs/installation/troubleshooting/ Troubleshooting + {% active_link /docs/troubleshooting/ Troubleshooting %}
    diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index 32653342fad..2d70544e2df 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -2,7 +2,7 @@

    Getting Started

      -
    • {% active_link /getting-started/ Installation %}
      • +
    • {% active_link /installation/ Installation %}
    • {% active_link /getting-started/onboarding/ Onboarding %}
    • {% active_link /getting-started/automation/ Automation %}
    • diff --git a/source/_includes/asides/installation_navigation.html b/source/_includes/asides/installation_navigation.html new file mode 100644 index 00000000000..5b9a435daf0 --- /dev/null +++ b/source/_includes/asides/installation_navigation.html @@ -0,0 +1,6 @@ +
      +
      +

      Installation

      + {{ content | toc_only }} +
      +
      diff --git a/source/_includes/assets/chevron_right.html b/source/_includes/assets/chevron_right.html new file mode 100644 index 00000000000..26b4a1a5998 --- /dev/null +++ b/source/_includes/assets/chevron_right.html @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/source/_includes/common-tasks/beta_version.md b/source/_includes/common-tasks/beta_version.md new file mode 100644 index 00000000000..25615bdd585 --- /dev/null +++ b/source/_includes/common-tasks/beta_version.md @@ -0,0 +1,71 @@ +## Run a beta version + +If you would like to test next release before anyone else, you can install the beta version. + +{% if page.installation == "os" or page.installation == "supervised" %} + +{% tabbed_block %} + +- title: From the UI + content: | + + 1. In your Home Assistant UI navigate to the Supervisor panel + 2. Navigate to the System tab + 3. Click the link that says "Join beta" + 4. Navigate to the Dashboard tab + 5. Install the update that is presented to you + +- title: From the CLI + content: | + + 1. Join the beta channel + + ```bash + ha supervisor options --channel beta + ``` + + 2. Reload the supervisor + + ```bash + ha supervisor reload + ``` + + 3. Update Home Assistant core to the latest beta version + + ```bash + ha core update + ``` + +{% endtabbed_block %} + + + +{% elsif page.installation == "container" %} + +```bash +ha os update --version {{current_version}} +``` + +{% elsif page.installation == "core" %} + +1. Switch to the user that is running Home Assistant + + ```bash + sudo -u homeassistant -H -s + ``` + +2. Activate the virtual environment that Home Assistant is running in + + ```bash + source /srv/homeassistant/bin/activate + ``` + +3. Download and install the beta version + + ```bash + pip3 install --pre --upgrade homeassistant + ``` + +4. When that is complete restart the service for it to use the new files. + +{% endif %} diff --git a/source/hassio/commandline.markdown b/source/_includes/common-tasks/commandline.md similarity index 89% rename from source/hassio/commandline.markdown rename to source/_includes/common-tasks/commandline.md index 9e5360ff931..bb03546d2bc 100644 --- a/source/hassio/commandline.markdown +++ b/source/_includes/common-tasks/commandline.md @@ -1,7 +1,4 @@ ---- -title: "Home Assistant via the command line" -description: "Command line utility to control Home Assistant." ---- +## Home Assistant via the command line

      @@ -10,7 +7,7 @@ Home Assistant upgrade process from the SSH command line On the SSH command line, you can use the `ha` command to retrieve logs, check the details of connected hardware, and more. -## Home Assistant +### Home Assistant ```bash ha core check @@ -25,7 +22,7 @@ ha core stop ha core update ``` -## Supervisor +### Supervisor ```bash ha supervisor info @@ -34,7 +31,7 @@ ha supervisor reload ha supervisor update ``` -## Host +### Host ```bash ha host reboot @@ -42,20 +39,22 @@ ha host shutdown ha host update ``` -## Hardware +### Hardware ```bash ha hardware info ha hardware audio ``` -## Usage examples +### Usage examples To update Home Assistant to a specific version, use the command: + ```bash -ha core update --version=x.y.z +ha core update --version x.y.z ``` -Replace x.y.z with the desired version like `--version=0.74.2` + +Replace x.y.z with the desired version like `--version {{current_version}}` You can get a better description of the CLI capabilities by typing `ha help`: @@ -91,6 +90,9 @@ Flags: Use "ha [command] --help" for more information about a command. ``` -## Console access +{% if page.installation == "os" %} +### Console access You can also access the Home Assistant Operating System via a directly connected keyboard and monitor, the console. To log in to the physical console the username is `root`, with no password. + +{% endif %} diff --git a/source/_includes/common-tasks/configuration_check.md b/source/_includes/common-tasks/configuration_check.md new file mode 100644 index 00000000000..2a5b598083e --- /dev/null +++ b/source/_includes/common-tasks/configuration_check.md @@ -0,0 +1,39 @@ +## Configuration check + +{% if page.installation == "os" or page.installation == "supervised" %} + +```bash +ha core check +``` + +{% elsif page.installation == "container" %} + +```bash +docker exec homeassistant python -m homeassistant --script check_config --config /config +``` + +_If your container name is something other than `homeassistant`, change that part._ + +{% elsif page.installation == "core" %} + +1. Switch to the user that is running Home Assistant + + ```bash + sudo -u homeassistant -H -s + ``` + +2. Activate the virtual environment that Home Assistant is running in + + ```bash + source /srv/homeassistant/bin/activate + ``` + +3. Run the configuration check + + ```bash + hass --script check_config + ``` + +4. When that is complete restart the service for it to use the new files. + +{% endif %} diff --git a/source/_includes/common-tasks/development_version.md b/source/_includes/common-tasks/development_version.md new file mode 100644 index 00000000000..05f38c199b2 --- /dev/null +++ b/source/_includes/common-tasks/development_version.md @@ -0,0 +1,59 @@ +## Run a development version + +If you want to stay on the bleeding-edge Home Assistant Core development branch, you can upgrade to `dev`. + +

      + + The `dev` branch is likely to be unstable. Potential consequences include loss of data and instance corruption. + +
      + +{% if page.installation == "os" or page.installation == "supervised" %} + +1. Join the dev channel + + ```bash + ha supervisor options --channel dev + ``` + +2. Reload the supervisor + + ```bash + ha supervisor reload + ``` + +3. Update Home Assistant core to the latest dev version + + ```bash + ha core update + ``` + +{% elsif page.installation == "container" %} + +```bash +ha os update --version {{current_version}} +``` + +{% elsif page.installation == "core" %} + +1. Switch to the user that is running Home Assistant + + ```bash + sudo -u homeassistant -H -s + ``` + +2. Activate the virtual environment that Home Assistant is running in + + ```bash + source /srv/homeassistant/bin/activate + ``` + +3. Download and install the version you want + + ```bash + pip3 install --upgrade git+git://github.com/home-assistant/home-assistant.git@dev + ``` + +4. When that is complete restart the service for it to use the new files. + +{% endif %} diff --git a/source/hassio/enable_i2c.markdown b/source/_includes/common-tasks/enable_i2c.md similarity index 84% rename from source/hassio/enable_i2c.markdown rename to source/_includes/common-tasks/enable_i2c.md index d04f55a64ea..24f69bec34c 100644 --- a/source/hassio/enable_i2c.markdown +++ b/source/_includes/common-tasks/enable_i2c.md @@ -1,18 +1,15 @@ ---- -title: "Enable I2C on the Home Assistant Operating System" -description: "Instructions on how to enable I2C on a Raspberry Pi" ---- +## Enable I2C Home Assistant using the Home Assistant Operating System is a managed environment, which means you can't use existing methods to enable the I2C bus on a Raspberry Pi. -## Step by step instructions +### Step by step instructions You will need: - SD card reader - SD card with Home Assistant Operating System flashed on it -### Step 1 - Access the Home Assistant Operating System boot partition +#### Step 1 - Access the Home Assistant Operating System boot partition Shutdown/turn-off your Home Assistant installation and unplug the SD card. Plug the SD card into an SD card reader and find a drive/file system named @@ -20,7 +17,7 @@ Plug the SD card into an SD card reader and find a drive/file system named use your operating systems disk management utility to find the SD card reader and make sure the first partition is available. -### Step 2 - Add files to enable I2C +#### Step 2 - Add files to enable I2C - In the root of the `hassos-boot` partition, add a new folder called `CONFIG`. - In the `CONFIG` folder, add another new folder called `modules`. @@ -35,7 +32,7 @@ and make sure the first partition is available. dtparam=i2c_arm=on ``` -### Step 3 - Start with the new configuration +#### Step 3 - Start with the new configuration - Insert the SD card back into your Raspberry Pi. - On startup, the `hassos-config.service` will automatically pickup the new @@ -45,7 +42,7 @@ and make sure the first partition is available. The I2C devices should now be present under /dev. -## From Home Assistant Operating System Terminal +### From Home Assistant Operating System Terminal Alternatively, by attaching a keyboard and screen to your device, you can access the physical terminal to the Home Assistant Operating System. diff --git a/source/hassio/haos_common_tasks.markdown b/source/_includes/common-tasks/file_access.md similarity index 54% rename from source/hassio/haos_common_tasks.markdown rename to source/_includes/common-tasks/file_access.md index c1449f5375b..f21403ed590 100644 --- a/source/hassio/haos_common_tasks.markdown +++ b/source/_includes/common-tasks/file_access.md @@ -1,15 +1,8 @@ ---- -title: "Home Assistant OS Common Tasks" -description: "Guides for common tasks when using Home Assistant OS" ---- - -This section will provide guides to some common tasks and information which you will need in order to run, maintain, and edit your Home Assistant OS system. For further details on any particular subject, make sure to refer to the documentation for specific add-ons or topics listed here. - ## Configuring access to files Your Home Assistant Operating server includes two repositories by default: The official core add-on repository, and the community add-on repository. All of the add-ons mentioned here can be installed by navigating to the add-on store using Supervisor > Add-on Store in the UI. -One of the first things to take care of after installing Home Assistant OS is to provide yourself access to files. There are several add-ons commonly used for this, and most users employ a mix of various add-ons. Default directories on the host are mapped to the add-ons so that they can be accessed by the services any particular add-on might provide. On the host system these directories exist on the `/data` partition at `/mnt/data/supervisor/`. +One of the first things to take care of after installing Home Assistant OS is to provide yourself access to files. There are several add-ons commonly used for this, and most users employ a mix of various add-ons. Default directories on the host are mapped to the add-ons so that they can be accessed by the services any particular add-on might provide. On the host system these directories exist on the `/data` partition at `/mnt/data/supervisor/`. Using any of the add-ons listed below,the following directories are made available for access: @@ -20,8 +13,6 @@ Using any of the add-ons listed below,the following directories are made availab - `share` - `ssl` - - --- ### Installing and using the Samba add-on @@ -67,74 +58,3 @@ There is no configuration required for editing files within your `/config` direc A more basic and light weight alternative to Visual Studio Code, the File Editor add-on provides access through Hass-Configurator, which is a web-based filesystem-browser and text-editor. YAML files are automatically checked for syntax errors while editing. This add-on can be installed via the add-on store from the official add-on repository. There is no configuration required for editing files within your `/config` directory. In order to enable access to further directories, editing the add-on configuration is required. See the add-on documentation for details. - ---- - -## Home Assistant OS Snapshots - -Snapshots are a backup of your Home Assistant and add-on data and configuration. They are stored in a compressed archive file (.tar). Snapshots are made from the Supervisor Snapshot panel. There is also a service available which allows you to trigger the creation of a snapshot from an automation. Backups are stored in the /backup directory. - -A full snapshot includes the following directories: - -* `config` -* `share` -* `addons` (only manually installed or created add-ons, not those installed from the store) -* `ssl` -* `media` - -A partial snapshot consists of any number of the above default directories and installed add-ons. - -### Making a Snapshot from the UI - -1. Go to Supervisor > Snapshots in the UI -2. Provide a name for the snapshot. -3. Choose full or partial. -4. Choose to password protect or not. Password protected snapshots cannot easily be browsed outside of Home Assistant OS -5. Click "Create" to begin the snapshot. - -### Restoring a Snapshot on a new install - -You can make use of snapshots which you have copied off of a previous install to restore to a new installation during the onboarding process. Follow the link at the bottom of the account creation page to upload your snapshot from the previous installation. - -For restoring a snapshot at any other time, vist the Supervisor Snapshot panel in your UI and use the following steps: - -1. Select "Upload Snapshot" from the icon in the upper right of the page. -2. Click on the folder icon to navigate to your snapshot .tar file and select it. - -When the upload is completed, you will be presented with the snapshot restore dialog for restoring it, and can then choose to restore in full or in part by manually selecting individual items. - -If the snapshot you are uploading is more than 1GB in size, it can be faster and more efficient to make use of the Samba add-on in order to transfer files to the `/backup` directory. - -The length of time it takes to create or restore snapshots will depend on how much you have to compress or decompress. - -If you're looking to slim down your snapshots, check if your configuration directory contains a large database file (`home-assistant_v2.db`). See the [`recorder`](https://www.home-assistant.io/components/recorder/) integration page for options to keep your database data down to a size that won't cause issues. Note the keep days, purge interval, and include/exclude options. - -When the restore is complete, Home Assistant will restart to apply the new settings. You will lose the connection to the UI and it will return once the restart is completed. - -### Creating snapshots using the Home Assistant Command Line Interface - -1. `ha sn list` - lists snapshots and their slugnames -2. `ha sn restore slugname` - restores a specific snapshot -3. `ha sn new --name nameofsnapshot` - create a snapshot - -Use `ha help` to see more info. - - -### Copying your snapshots to another location - -You often need a snapshot in case your system has crashed. If you only store them on the crashed device, you won't be able to access it easily. We recommend that you manually copy them from `/backup` to another machine on occasion. Or even better, create an automation to handle that, or make use of one of the following add-ons: - - - [Google Drive Backup](https://github.com/sabeechen/hassio-google-drive-backup) - - - [Dropbox Sync](https://github.com/danielwelch/hassio-dropbox-sync) - - - [Nextcloud Backup](https://github.com/Sebclem/hassio-nextcloud-backup) - - - [Samba backup](https://github.com/thomasmauerer/hassio-addons/tree/master/samba-backup) - - - [Remote Backup (uses scp)](https://github.com/overkill32/hassio-remote-backup) - - -### Lost Password and password reset - -Please refer to the [I'm locked out!](https://www.home-assistant.io/docs/locked_out/#home-assistant-including-supervised) documentation page. diff --git a/source/hassio/flashing_n2_otg.markdown b/source/_includes/common-tasks/flashing_n2_otg.md similarity index 89% rename from source/hassio/flashing_n2_otg.markdown rename to source/_includes/common-tasks/flashing_n2_otg.md index 20b692355c9..9cb6b66184b 100644 --- a/source/hassio/flashing_n2_otg.markdown +++ b/source/_includes/common-tasks/flashing_n2_otg.md @@ -1,13 +1,10 @@ ---- -title: "Flashing an ODROID-N2+" -description: "Using Petitboot and OTG-USB to flash the eMMC on your Odroid N2" ---- +## Flashing an ODROID-N2+ Home Assistant can be flashed to an ODROID-N2+ by connecting the device directly to your computer via the USB-OTG connection on the front of the board. The device contains the Petitboot bootloader, which allows the ODROID-N2+ storage to show up as it were a USB drive. _All these instructions work the same for the ODROID-N2 (non-plus version)._ -## What you will need +#### What you will need To flash your eMMC using Petitboot and OTG-USB, you will need the following items: @@ -15,7 +12,7 @@ To flash your eMMC using Petitboot and OTG-USB, you will need the following item - USB keyboard - USB 2.0 to micro-USB cable -### Enabling SPI boot mode +#### Enabling SPI boot mode Remove the case of your ODROID-N2+ @@ -27,7 +24,7 @@ Next, locate the toggle for boot mode and switch it from MMC to SPI. Connect a USB keyboard and HDMI connected monitor to your ODROID-N2+, and then connect power. -### Enabling USB drive mode +#### Enabling USB drive mode The ODROID-N2+ will now boot into a terminal. Select `Exit to shell` from the menu. @@ -46,7 +43,7 @@ This will configure the ODROID-N2+ and OTG to act as a memory card reader. ums /dev/mmcblk0 ``` -### Flashing Home Assistant +#### Flashing Home Assistant Connect the ODROID-N2+ to your PC via the micro-USB port at the front of the ODROID-N2+. When the ODROID-N2 is recognized as a USB connected storage device, you can flash the eMMC with [Etcher](https://www.balena.io/etcher/) using the latest stable version of Home Assistant OS for the [ODROID-N2+](https://github.com/home-assistant/operating-system/releases/latest) (hassos_odroid-n2-XXXX.img.gz). @@ -54,4 +51,4 @@ When the flash process is complete, disconnect the ODROID-N2+ from your PC and r Once it is back in its case, connect your ODROID-N2+ to your network with an Ethernet cable and plug in power. -If your router supports mDNS, you will be able to reach your installation on `http://homeassistant.local:8123`. If your network doesn’t support mDNS, you’ll have to use the IP address of your ODROID-N2+ instead of `homeassistant.local`. For example, `http://192.168.0.9:8123`. You should be able to find the IP address of your ODROID-N2+ from the admin interface of your router. +If your router supports mDNS, you will be able to reach your installation on `http://homeassistant.local:8123`. If your network doesn’t support mDNS, you’ll have to use the IP address of your ODROID-N2+ instead of `homeassistant.local`. For example, `http://192.168.0.9:8123`. You should be able to find the IP address of your ODROID-N2+ from the admin interface of your router. \ No newline at end of file diff --git a/source/_includes/common-tasks/lost_password.md b/source/_includes/common-tasks/lost_password.md new file mode 100644 index 00000000000..7d86e4eb769 --- /dev/null +++ b/source/_includes/common-tasks/lost_password.md @@ -0,0 +1,3 @@ +## Lost Password and password reset + +Please refer to the [I'm locked out!](https://www.home-assistant.io/docs/locked_out/#home-assistant-including-supervised) documentation page. \ No newline at end of file diff --git a/source/_includes/common-tasks/snapshots.md b/source/_includes/common-tasks/snapshots.md new file mode 100644 index 00000000000..b806173f345 --- /dev/null +++ b/source/_includes/common-tasks/snapshots.md @@ -0,0 +1,63 @@ +## Snapshots + +Snapshots are a backup of your Home Assistant and add-on data and configuration. They are stored in a compressed archive file (.tar). Snapshots are made from the Supervisor Snapshot panel. There is also a service available which allows you to trigger the creation of a snapshot from an automation. Backups are stored in the /backup directory. + +A full snapshot includes the following directories: + +* `config` +* `share` +* `addons` (only manually installed or created add-ons, not those installed from the store) +* `ssl` +* `media` + +A partial snapshot consists of any number of the above default directories and installed add-ons. + +### Making a Snapshot from the UI + +1. Go to Supervisor > Snapshots in the UI +2. Provide a name for the snapshot. +3. Choose full or partial. +4. Choose to password protect or not. Password protected snapshots cannot easily be browsed outside of Home Assistant OS +5. Click "Create" to begin the snapshot. + +### Restoring a Snapshot on a new install + +You can make use of snapshots which you have copied off of a previous install to restore to a new installation during the onboarding process. Follow the link at the bottom of the account creation page to upload your snapshot from the previous installation. + +For restoring a snapshot at any other time, vist the Supervisor Snapshot panel in your UI and use the following steps: + +1. Select "Upload Snapshot" from the icon in the upper right of the page. +2. Click on the folder icon to navigate to your snapshot .tar file and select it. + +When the upload is completed, you will be presented with the snapshot restore dialog for restoring it, and can then choose to restore in full or in part by manually selecting individual items. + +If the snapshot you are uploading is more than 1GB in size, it can be faster and more efficient to make use of the Samba add-on in order to transfer files to the `/backup` directory. + +The length of time it takes to create or restore snapshots will depend on how much you have to compress or decompress. + +If you're looking to slim down your snapshots, check if your configuration directory contains a large database file (`home-assistant_v2.db`). See the [`recorder`](https://www.home-assistant.io/components/recorder/) integration page for options to keep your database data down to a size that won't cause issues. Note the keep days, purge interval, and include/exclude options. + +When the restore is complete, Home Assistant will restart to apply the new settings. You will lose the connection to the UI and it will return once the restart is completed. + +### Creating snapshots using the Home Assistant Command Line Interface + +1. `ha snapshot list` - lists snapshots and their slugnames +2. `ha snapshot restore slugname` - restores a specific snapshot +3. `ha snapshot new --name nameofsnapshot` - create a snapshot + +Use `ha help` to see more info. + + +### Copying your snapshots to another location + +You often need a snapshot in case your system has crashed. If you only store them on the crashed device, you won't be able to access it easily. We recommend that you manually copy them from `/backup` to another machine on occasion. Or even better, create an automation to handle that, or make use of one of the following add-ons: + + - [Google Drive Backup](https://github.com/sabeechen/hassio-google-drive-backup) + + - [Dropbox Sync](https://github.com/danielwelch/hassio-dropbox-sync) + + - [Nextcloud Backup](https://github.com/Sebclem/hassio-nextcloud-backup) + + - [Samba backup](https://github.com/thomasmauerer/hassio-addons/tree/master/samba-backup) + + - [Remote Backup (uses scp)](https://github.com/overkill32/hassio-remote-backup) \ No newline at end of file diff --git a/source/_includes/common-tasks/specific_version.md b/source/_includes/common-tasks/specific_version.md new file mode 100644 index 00000000000..6d11461ad50 --- /dev/null +++ b/source/_includes/common-tasks/specific_version.md @@ -0,0 +1,41 @@ +## Run a specific version + +{% assign current_version = site.current_major_version | append: "." | append: site.current_minor_version | append: "." | append: site.current_patch_version %} + +In the event that a Home Assistant Core version doesn't play well with your hardware setup, you can downgrade to a previous release. In this example `{{current_version}}` is used as the target version but you can choose the version you desire to run. + +{% if page.installation == "os" or page.installation == "supervised" %} + +```bash +ha core update --version {{current_version}} +``` + +{% elsif page.installation == "container" %} + +```bash +ha os update --version {{current_version}} +``` + +{% elsif page.installation == "core" %} + +1. Switch to the user that is running Home Assistant + + ```bash + sudo -u homeassistant -H -s + ``` + +2. Activate the virtual environment that Home Assistant is running in + + ```bash + source /srv/homeassistant/bin/activate + ``` + +3. Download and install the version you want + + ```bash + pip3 install homeassistant=={{current_version}} + ``` + +4. When that is complete restart the service for it to use the new files. + +{% endif %} diff --git a/source/hassio/installing_third_party_addons.markdown b/source/_includes/common-tasks/third-party-addons.md similarity index 86% rename from source/hassio/installing_third_party_addons.markdown rename to source/_includes/common-tasks/third-party-addons.md index fd812d71cb9..2a7917aa689 100644 --- a/source/hassio/installing_third_party_addons.markdown +++ b/source/_includes/common-tasks/third-party-addons.md @@ -1,7 +1,4 @@ ---- -title: "Installing third-party add-ons" -description: "Instructions on how to get started using third-party add-ons." ---- +## Installing third-party add-ons Home Assistant allows anyone to create add-on repositories to share their add-ons easily. To try this locally, you can use our example add-on repository at @@ -25,4 +22,4 @@ Add the URL of the repository and then press "Add". A new card for the repositor ### Help: Repository is not showing up -If you have added a repository, but it's not showing up, it means that the repository contains invalid configuration. Go to the Supervisor panel and then the System tab to find the System log. It should tell you what went wrong. Report this information to the repository author. +If you have added a repository, but it's not showing up, it means that the repository contains invalid configuration. Go to the Supervisor panel and then the System tab to find the System log. It should tell you what went wrong. Report this information to the repository author. \ No newline at end of file diff --git a/source/_includes/common-tasks/update.md b/source/_includes/common-tasks/update.md new file mode 100644 index 00000000000..57f81f276c6 --- /dev/null +++ b/source/_includes/common-tasks/update.md @@ -0,0 +1,90 @@ +## Update + +Best practice for updating a Home Assistant installation: + +1. Backup your installation, using the snapshot functionality Home Assistant offers. +1. Check the release notes for breaking changes on [Home Assistant release notes](https://github.com/home-assistant/home-assistant/releases). Be sure to check all release notes between the version you are running and the one you are upgrading to. Use the search function in your browser (`CTRL + f` / `CMD + f`) and search for **Breaking Changes**. +{% if page.installation == "os" or page.installation == "supervised" %} +1. Check your configuration using the [Check Home Assistant configuration](/addons/check_config/) add-on. +1. If the check passes, you can safely update. If not, update your configuration accordingly. +1. Update Home Assistant. +{% endif %} + +{% if page.installation == "os" or page.installation == "supervised" %} + +To update Home Assistant Core when you run Home Assistant {{ page.installation_name }} you have 2 options. + +{% tabbed_block %} + +- title: Using the UI + content: | + + 1. Open your Home Assistant UI + 2. Navigate to the Supervisor panel + 3. On the Dashboard tab you will be presented with an update notification + + _If you do not see that notification you can navigate to the System tab. and click the "Reload Supervisor" button._ + +- title: Using the CLI + content: | + + ```bash + ha core update + ``` + +{% endtabbed_block %} + +{% elsif page.installation == "container" %} + +{% tabbed_block %} + +- title: Docker CLI + content: | + + **First start with pulling the new container.** + + ```bash + docker pull homeassistant/home-assistant:stable + ``` + + You can also use spesific containers for your hardware. Like Raspberry pi 4: + + ```bash + docker pull homeassistant/raspberrypi4-homeassistant:stable + ``` + + **[You need to recreate the container with the new image.](/getting-started)** + +- title: Docker Compose + content: | + + ```bash + docker-compose pull homeassistant + docker-compose up -d + ``` + +{% endtabbed_block %} + +{% elsif page.installation == "core" %} + +1. Switch to the user that is running Home Assistant + + ```bash + sudo -u homeassistant -H -s + ``` + +2. Activate the virtual environment that Home Assistant is running in + + ```bash + source /srv/homeassistant/bin/activate + ``` + +3. Download and install the new version + + ```bash + pip3 install --upgrade homeassistant + ``` + +4. When that is complete restart the service for it to use the new files. + +{% endif %} diff --git a/source/_includes/getting-started/next_step.html b/source/_includes/getting-started/next_step.html new file mode 100644 index 00000000000..ebd26ee7e8d --- /dev/null +++ b/source/_includes/getting-started/next_step.html @@ -0,0 +1,7 @@ + + +
      +

      {{ include.step }}

      + {% include assets/chevron_right.html %} +
      +       diff --git a/source/_includes/installation/container.md b/source/_includes/installation/container.md new file mode 100644 index 00000000000..873533850b9 --- /dev/null +++ b/source/_includes/installation/container.md @@ -0,0 +1,137 @@ +## Install Home Assistant Container + +{% if page.installation_type != 'alternative' %} +These below instructions are for an installation of Home Assistant Container running in your own container environment, which you manage yourself. Any [OCI](https://opencontainers.org/) compatible runtime can be used, however this guide will focus on installing it with Docker. + +
      +Prerequisites + +This guide assumes that you already have an operating system setup and a container runtime installed (like Docker). +
      + +### Platform Installation + +Installation with Docker is straightforward. Adjust the following command so that `/PATH_TO_YOUR_CONFIG` points at the folder where you want to store your configuration and run it. +{% endif %} + +{% if page.installation_type == 'raspberrypi' %} +#### Raspberry pi 3 + + {% include installation/container/cli.md image="homeassistant/raspberrypi3:stable" %} + +#### Raspberry pi 4 + + {% include installation/container/cli.md image="homeassistant/raspberrypi4:stable" %} + +{% elsif page.installation_type == 'alternative' %} + {% include installation/container/alternative.md %} + +{% else %} + {% include installation/container/cli.md image="homeassistant/home-assistant:stable" %} +{% endif %} + +### Restart Home Assistant + +If you change the configuration you have to restart the server. To do that you have 3 options. + +1. In your Home Assistant UI go to the **Configuration** panel -> **Server management** and click the "Restart" button. +2. You can go to the **Developer Tools** -> **Services**, select the service `homeassistant.restart` and click "Call Service". +3. Restart it from a terminal. + +{% tabbed_block %} + +- title: Docker CLI + content: | + + ```bash + docker restart homeassistant + ``` + +- title: Docker Compose + content: | + + ```bash + docker-compose restart + ``` + +{% endtabbed_block %} + +### Docker Compose + +As the Docker command becomes more complex, switching to `docker-compose` can be preferable and support automatically restarting on failure or system restart. Create a `docker-compose.yml` file: + +{% if page.installation_type == 'raspberrypi' %} +#### Raspberry pi 3 + + {% include installation/container/compose.md image="homeassistant/raspberrypi3:stable" %} + +#### Raspberry pi 4 + + {% include installation/container/compose.md image="homeassistant/raspberrypi4:stable" %} +{% else %} + {% include installation/container/compose.md image="homeassistant/home-assistant:stable" %} +{% endif %} + +Start it by running: + +```bash +docker-compose up -d +``` + +### Exposing Devices + +In order to use Z-Wave, Zigbee or other integrations that require access to devices, you need to map the appropriate device into the container. Ensure the user that is running the container has the correct privileges to access the `/dev/tty*` file, then add the device mapping to your container instructions: + +{% tabbed_block %} + +- title: Docker CLI + content: | + + ```bash + docker run ... --device /dev/ttyUSB0:/dev/ttyUSB0 ... + ``` + +- title: Docker Compose + content: | + + ```yaml + version: '3' + services: + homeassistant: + ... + devices: + - /dev/ttyUSB0:/dev/ttyUSB0 + ``` + +{% endtabbed_block %} + +### Optimizations + +The Home Assistant Container is using an alternative memory allocation library [jemalloc](http://jemalloc.net/) for better memory management and Python runtime speedup. + +As jemalloc can cause issues on certain hardware, it can be disabled by passing the environment variable `DISABLE_JEMALLOC` with any value, for example: + +{% tabbed_block %} + +- title: Docker CLI + content: | + + ```bash + docker run ... -e "DISABLE_JEMALLOC=true" ... + ``` + +- title: Docker Compose + content: | + + ```yaml + version: '3' + services: + homeassistant: + ... + environment: + DISABLE_JEMALLOC: true + ``` + +{% endtabbed_block %} + +The error message `: Unsupported system page size` is one known indicator. diff --git a/source/_includes/installation/container/alternative.md b/source/_includes/installation/container/alternative.md new file mode 100644 index 00000000000..cf874d70206 --- /dev/null +++ b/source/_includes/installation/container/alternative.md @@ -0,0 +1,139 @@ +### Synology NAS + +As Synology within DSM now supports Docker (with a neat UI), you can simply install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see + +The steps would be: + +- Install "Docker" package on your Synology NAS +- Launch Docker-app and move to "Registry"-section +- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "stable" tag. +- Wait for some time until your NAS has pulled the image +- Move to the "Image"-section of the Docker-app +- Click on "Launch" +- Choose a container-name you want (e.g., "homeassistant") +- Click on "Advanced Settings" +- Set "Enable auto-restart" if you like +- Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount path" has to be "/config", so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named "config" or "homeassistant/config" to avoid confusion when referencing it within service calls. +- Within "Network" select "Use same network as Docker Host" +- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +- Confirm the "Advanced Settings" +- Click on "Next" and then "Apply" +- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`) + +If you are using the built-in firewall, you must also add the port 8123 to allowed list. This can be found in "Control Panel -> Security" and then the Firewall tab. Click "Edit Rules" besides the Firewall Profile dropdown box. Create a new rule and select "Custom" for Ports and add 8123. Edit Source IP if you like or leave it at default "All". Action should stay at "Allow". + +To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS: + + + + +
      + +[See this page for accessing the Terminal via SSH](https://www.synology.com/en-global/knowledgebase/DSM/tutorial/General_Setup/How_to_login_to_DSM_with_root_permission_via_SSH_Telnet) + +
      + +Adjust the following Terminal command as follows : + +- Replace `/PATH_TO_YOUR_CONFIG` points at the folder where you want to store your configuration +- Replace `/PATH_TO_YOUR_USB_STICK` matches the path for your USB stick (e.g., `/dev/ttyACM0` for most Synology users) +- Replace "Australia/Melbourne" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) + +Run it in Terminal. + +```bash +sudo docker run --restart always -d --name homeassistant -v /PATH_TO_YOUR_CONFIG:/config --device=/PATH_TO_YOUR_USB_STICK -e TZ=Australia/Melbourne --net=host homeassistant/home-assistant:stable +``` + +Complete the remainder of the Z-Wave configuration by [following the instructions here.](/docs/z-wave/installation) + +Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following: + +- Go to the Docker-app and move to "Registry"-section +- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "stable" tag. +- Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar) +- Move to "Container"-section +- Stop your container if it's running +- Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your configuration-directory +- Start the container again - it will then boot up with the new Home Assistant image + +Remark: to restart your Home Assistant within Synology NAS, you just have to do the following: + +- Go to the Docker-app and move to "Container"-section +- Right-click on it and select "Action"->"Restart". + +
      + +If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assistant on Synology Docker these instructions do not correctly configure the container to access the USB devices. To configure these devices on your Synology Docker Home Assistant you can follow the instructions provided [here](https://philhawthorne.com/installing-home-assistant-io-on-a-synology-diskstation-nas/) by Phil Hawthorne. + +
      + +### QNAP NAS + +As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using Docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see + +The steps would be: + +- Install "Container Station" package on your Qnap NAS +- Launch Container Station and move to "Create Container"-section +- Search image "homeassistant/home-assistant" with Docker Hub and click on "Install" + Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is "homeassistant/armhf-homeassistant" +- Choose "stable" version and click next +- Choose a container-name you want (e.g., "homeassistant") +- Click on "Advanced Settings" +- Within "Shared Folders" click on "Volume from host" > "Add" and choose either an existing folder or add a new folder. The "mount point has to be `/config`, so that Home Assistant will use it for the configuration and logs. +- Within "Network" and select Network Mode to "Host" +- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) +- Click on "Create" +- Wait for some time until your NAS has created the container +- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example `http://192.xxx.xxx.xxx:8123`) + +Remark: To update your Home Assistant on your Docker within Qnap NAS, you just remove container and image and do steps again (Don't remove "config" folder). + +If you want to use a USB Bluetooth adapter or Z-Wave USB stick with Home Assistant on Qnap Docker, follow those steps: + +#### Z-Wave + +- Connect to your NAS over SSH +- Load cdc-acm kernel module(when NAS restart need to run this command) + `insmod /usr/local/modules/cdc-acm.ko` +- Find USB devices attached. Type command: + `ls /dev/tty*` + The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. Like : `ttyACM0` + +- Run Docker command: + + ```bash + docker run --init --name homeassistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e TZ=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable + ``` + + `-v` is your configuration path + `-e` is set timezone + +- Edit `configuration.yaml` + +```yaml +zwave: + usb_path: /dev/ttyACM0 +``` + +That will tell Home Assistant where to look for our Z-Wave radio. + +#### Bluetooth + +- Connect to your NAS over SSH +- Run Docker command: + + ```bash + docker run --init --name homeassistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e TZ=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable + ``` + + First `-v` is your configuration path + `-e` is set timezone + +- Edit the `configuration.yaml` file + +```yaml +device_tracker: + - platform: bluetooth_tracker +``` \ No newline at end of file diff --git a/source/_includes/installation/container/cli.md b/source/_includes/installation/container/cli.md new file mode 100644 index 00000000000..0f9c792793b --- /dev/null +++ b/source/_includes/installation/container/cli.md @@ -0,0 +1,45 @@ +{% tabbed_block %} + +- title: Install + content: | + + ```bash + docker run --init -d \ + --name homeassistant \ + --restart=unless-stopped \ + -v /etc/localtime:/etc/localtime:ro \ + -v /PATH_TO_YOUR_CONFIG:/config \ + --network=host \ + {{ include.image }} + ``` + +- title: Update + content: | + + ```bash + # if this returns "Image is up to date" then you can stop here + docker pull {{ include.image }} + ``` + + ```bash + # stop the running container + docker stop homeassistant + ``` + + ```bash + # remove it from Docker's list of containers + docker rm homeassistant + ``` + + ```bash + # finally, start a new one + docker run --init -d \ + --name homeassistant \ + --restart=unless-stopped \ + -v /PATH_TO_YOUR_CONFIG:/config \ + -v /etc/localtime:/etc/localtime:ro \ + --network=host \ + {{ include.image }} + ``` + +{% endtabbed_block %} diff --git a/source/_includes/installation/container/compose.md b/source/_includes/installation/container/compose.md new file mode 100644 index 00000000000..db5a16953ef --- /dev/null +++ b/source/_includes/installation/container/compose.md @@ -0,0 +1,12 @@ +```yaml + version: '3' + services: + homeassistant: + container_name: homeassistant + image: {{ include.image }} + volumes: + - /PATH_TO_YOUR_CONFIG:/config + - /etc/localtime:/etc/localtime:ro + restart: unless-stopped + network_mode: host +``` \ No newline at end of file diff --git a/source/_includes/installation/core.md b/source/_includes/installation/core.md new file mode 100644 index 00000000000..aaaf59c4de4 --- /dev/null +++ b/source/_includes/installation/core.md @@ -0,0 +1,85 @@ +## Install Home Assistant Core + +
      +Prerequisites + +This guide assumes that you already have an operating system setup and have installed Python {{site.installation.versions.python}} (including the package `python3-dev`) or newer. +
      + +### Install dependencies + +Before you start make sure your system is fully updated, all packages in this guide are installed with `apt`, if your OS does not have that, look for alternatives. + +```bash +sudo apt-get update +sudo apt-get upgrade -y +``` + +Install the dependencies: + +```bash +sudo apt-get install -y python3 python3-dev python3-venv python3-pip libffi-dev libssl-dev libjpeg-dev zlib1g-dev autoconf build-essential libopenjp2-7 libtiff5 +``` + +### Create an account + +Add an account for Home Assistant Core called `homeassistant`. +Since this account is only for running Home Assistant Core the extra arguments of `-rm` is added to create a system account and create a home directory. +{%- if site.installation.types[page.installation_type].board %} +The arguments `-G dialout,gpio,i2c` adds the user to the `dialout`, `gpio` and the `i2c` group. The first is required for using Z-Wave and Zigbee controllers, while the second is required to communicate with GPIO. + +```bash +sudo useradd -rm homeassistant -G dialout,gpio,i2c +``` + +{% else %} + +```bash +sudo useradd -rm homeassistant +``` + +{% endif %} + +### Create the virtual environment + +First we will create a directory for the installation of Home Assistant Core and change the owner to the `homeassistant` account. + +```bash +sudo mkdir /srv/homeassistant +sudo chown homeassistant:homeassistant /srv/homeassistant +``` + +Next up is to create and change to a virtual environment for Home Assistant Core. This will be done as the `homeassistant` account. + +```bash +sudo -u homeassistant -H -s +cd /srv/homeassistant +python{{site.installation.versions.python}} -m venv . +source bin/activate +``` + +Once you have activated the virtual environment (notice the prompt change to `(homeassistant) homeassistant@raspberrypi:/srv/homeassistant $`) you will need to run the following command to install a required Python package. + +```bash +python3 -m pip install wheel +``` + +Once you have installed the required Python package it is now time to install Home Assistant Core! + +```bash +pip3 install homeassistant +``` + +Start Home Assistant Core for the first time. This will complete the installation for you, automatically creating the `.homeassistant` configuration directory in the `/home/homeassistant` directory, and installing any basic dependencies. + +```bash +hass +``` + +You can now reach your installation on your Raspberry Pi over the web interface on `http://homeassistant.local:8123`. + +
      + +When you run the `hass` command for the first time, it will download, install and cache the necessary libraries/dependencies. This procedure may take anywhere between 5 to 10 minutes. During that time, you may get "site cannot be reached" error when accessing the web interface. This will only happen for the first time, and subsequent restarts will be much faster. + +
      diff --git a/source/_includes/installation/core/linux.markdown b/source/_includes/installation/core/linux.markdown new file mode 100644 index 00000000000..e69de29bb2d diff --git a/source/_includes/installation/core/macos.markdown b/source/_includes/installation/core/macos.markdown new file mode 100644 index 00000000000..e69de29bb2d diff --git a/source/_includes/installation/core/windows.markdown b/source/_includes/installation/core/windows.markdown new file mode 100644 index 00000000000..e69de29bb2d diff --git a/source/_includes/installation/operating_system.md b/source/_includes/installation/operating_system.md new file mode 100644 index 00000000000..81e306b4bc8 --- /dev/null +++ b/source/_includes/installation/operating_system.md @@ -0,0 +1,183 @@ +## Install Home Assistant Operating System + +{% assign release_url = "https://github.com/home-assistant/operating-system/releases/download" %} + +Follow this guide if you want to get started with Home Assistant easily or if you have little to no Linux experience + +{% if site.installation.types[page.installation_type].board %} +{% if page.installation_type == 'raspberrypi' %} + +### Suggested Hardware + +We will need a few things to get started with installing Home Assistant. Links below lead to Amazon US. If you’re not in the US, you should be able to find these items in web stores in your country. + +- [Power Supply](https://www.raspberrypi.org/help/faqs/#powerReqs) (at least 3A) +- [Micro SD Card](https://amzn.to/2X0Z2di). Ideally get one that is [Application Class 2](https://www.sdcard.org/developers/overview/application/index.html) as they handle small I/O much more consistently than cards not optimized to host applications. A 32 GB or bigger card is recommended. +- SD Card reader. This is already part of most laptops, but you can purchase a [standalone USB adapter](https://amzn.to/2WWxntY) if you don't have one. The brand doesn't matter, just pick the cheapest. +- Ethernet cable. Home Assistant can work with Wi-Fi, but an Ethernet connection would be more reliable. + +{% endif %} + +### Write the image to your installation media + +1. Attach the installation media ({{site.installation.types[page.installation_type].installation_media}}) to your computer +2. Download and start Balena Etcher +3. Select "Flash from URL" +![etcher_from_url](/images/installation/etcher1.png) + +4. Get the URL for your {{site.installation.types[page.installation_type].board}}: +{% if site.installation.types[page.installation_type].variants.size > 1 %} +{% tabbed_block %} +{% for variant in site.installation.types[page.installation_type].variants %} + +- title: {{ variant.name }} + content: | + + ```text + {{release_url}}/{{site.installation.versions.os}}/hassos_{{ variant.key }}-{{site.installation.versions.os}}.img.xz + ``` + + {% if variant.key == "odroid-n2" %} + [Guide: Flashing Odroid-N2 using OTG-USB](/hassio/flashing_n2_otg/) + {% elsif variant.key == "rpi4" %} + _(To use the full 8GB of memory on the 8GB model 64-bit is **required**)_ + {% elsif variant.key == "rpi4-64" or variant.key == "rpi3-64" %} + _(For GPIO and HAT 32-bit is **required**)_ + {% endif %} + +{% endfor %} +{% endtabbed_block %} +{% else %} + +```text +{{release_url}}/{{site.installation.versions.os}}/hassos_{{ site.installation.types[page.installation_type].variants[0].key }}-{{site.installation.versions.os}}.img.xz +``` + +{% endif %} + +_Select and copy the URL or use the "copy" button that appear when you hover it._ + +1. Paste the URL for your {{site.installation.types[page.installation_type].board}} into Balena Etcher and click "OK" +![etcher_from_url_paste](/images/installation/etcher2.png) +6. Balena Etcher will now download the image, when that is done click "Select target" +![etcher_select_target](/images/installation/etcher3.png) +7. Select the {{site.installation.types[page.installation_type].installation_media}} you want to use for your {{site.installation.types[page.installation_type].board}} +![etcher_select_target](/images/installation/etcher4.png) +8. Click on "Flash!" to start writing the image +![etcher_select_target](/images/installation/etcher5.png) +9. When Balena Etcher is finished writing the image you will get this confirmation +![etcher_select_target](/images/installation/etcher6.png) + +### Start up your {{site.installation.types[page.installation_type].board}} + +1. Insert the installation media ({{site.installation.types[page.installation_type].installation_media}}) you just created +2. Attach a ethernet cable for network. +3. Attach a cable for power +4. Within a few minutes you will be able to reach Home Assistant on homeassistant.local:8123. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at homeassistant:8123 or `http://X.X.X.X:8123` (replace X.X.X.X with your {{site.installation.types[page.installation_type].board}}’s IP address). + + +{% else %} + +### Download the appropriate image + +{% if page.installation_type == 'nuc' %} +- [Intel NUC][intel-nuc] +{% else %} +- [VirtualBox][vdi] (.vdi) +{% if page.installation_type == 'macos' %} +- [KVM][qcow2] (.qcow2) +{% endif %} +{% if page.installation_type == 'windows' or page.installation_type == 'linux' %} +- [KVM][qcow2] (.qcow2) +- [Vmware Workstation][vmdk] (.vmdk) +{% elsif page.installation_type == 'alternative' %} +- [KVM/Proxmox][qcow2] (.qcow2) +- [VMware ESXi/vSphere][Virtual Appliance] (.ova) +{% elsif page.installation_type == 'windows' %} +- [Hyper-V][vhdx] (.vhdx) +{% endif %} +{% endif %} +{% if page.installation_type == "nuc" %} + +1. Put the SD card in your card reader. +2. Open balenaEtcher, select the Home Assistant image and flash it to the SD card. +3. Unmount the SD card and remove it from your card reader. +{% else %} + +### Create the Virtual Machine + +Load the appliance image into your virtual machine software. (Note: You are free to assign as much resources as you wish to the VM, please assign enough based on your add-on needs) + +Minimum recommended assignments: + +- 2GB RAM +- 32GB Storage +- 1vCPU + +_All these can be extended if your usage calls for more resources._ + +### Hypervisor specific configuration + +{% tabbed_block %} + +- title: VirtualBox + content: | + 1. Create a new virtual machine + 2. Select “Other Linux (64Bit) + 3. Select “Use an existing virtual hard disk file”, select the VDI file from above + 4. Edit the “Settings” of the VM and go “System” then Motherboard and Enable EFI + 5. Then “Network” “Adapter 1” Bridged and your adapter. + +- title: KVM + content: | + 1. Create a new virtual machine in `virt-manager` + 2. Select “Import existing disk image”, provide the path to the QCOW2 image above + 3. Choose “Generic Default” for the operating system + 4. Check the box for “Customize configuration before install” + 5. Select your bridge under “Network Selection” + 6. Under customization select “Overview” -> “Firmware” -> “UEFI x86_64: …”.**** + +{% if page.installation_type == 'windows' or page.installation_type == 'linux' %} + +- title: Vmware Workstation + content: | + 1. Create a new virtual machine + 2. Select “Custom”, make it compatible with the default of Workstation and ESX + 3. Choose “I will install the operating system later”, select “Linux” -> “Other Linux 5.x or later kernel 64-bit” + 4. Select “Use Bridged Networking” + 5. Select “Use an existing virtual disk” and select the VMDK file above, + + After creation of VM go to “Settings” and “Options” then “Advanced” and select “Firmware type” to “UEFI”. + +{% elsif page.installation_type == 'alternative' %} + +- title: VMware ESXi/vSphere + content: | + Use the “E1001” or “E1001E” virtual network adapater. There are confirmed mDNS/Multicast discovery issues when using VMware’s “VMXnet3” virtual network adapter. + +{% elsif page.installation_type == 'windows' %} +- title: Hyper-V + content: | +
      + Hyper-V does not have USB support +
      + + 1. Create a new virtual machine + 2. Select “Generation 2” + 3. Select “Connection -> “Your Virtual Switch that is bridged” + 4. Select “Use an existing virtual hard disk” and select the VHDX file from above + + After creation go to “Settings” -> “Security” and deselect “Enable Secure Boot”. +{% endif %} + +{% endtabbed_block %} +{% endif %} + +{% endif %} + +[intel-nuc]: {{release_url}}/{{site.installation.versions.os}}/hassos_intel-nuc-{{site.installation.versions.os}}.img.xz +[vmdk]: {{release_url}}/{{site.installation.versions.os}}/hassos_ova-{{site.installation.versions.os}}.vmdk.xz +[vhdx]: {{release_url}}/{{site.installation.versions.os}}/hassos_ova-{{site.installation.versions.os}}.vhdx.xz +[vdi]: {{release_url}}/{{site.installation.versions.os}}/hassos_ova-{{site.installation.versions.os}}.vdi.xz +[qcow2]: {{release_url}}/{{site.installation.versions.os}}/hassos_ova-{{site.installation.versions.os}}.qcow2.xz +[Virtual Appliance]: {{release_url}}/{{site.installation.versions.os}}/hassos_ova-{{site.installation.versions.os}}.ova diff --git a/source/_includes/installation/supervised.md b/source/_includes/installation/supervised.md new file mode 100644 index 00000000000..f255342cbe9 --- /dev/null +++ b/source/_includes/installation/supervised.md @@ -0,0 +1,12 @@ +## Install Home Assistant Supervised + +
      + +This way of running Home Assistant will require the most of you. It also have strict requirements you need to follow. + +Unless you really need this installation type, you should install Home Assistant OS (this can also be a [virtual machine](#install-home-assistant-operating-system)), or [Home Assistant Container](#install-home-assistant-container). + +
      + +1. First make sure you understand the requirements. +2. Then head over to home-assistant/supervised-installer to set it up. diff --git a/source/_includes/site/sidebar.html b/source/_includes/site/sidebar.html index 375d78fd713..fa4afecb2eb 100644 --- a/source/_includes/site/sidebar.html +++ b/source/_includes/site/sidebar.html @@ -3,6 +3,10 @@ {% assign root = url_parts[1] %} {% if root == 'integrations' %} {% include asides/component_navigation.html %} + {% elsif root == 'installation' %} + {% include asides/installation_navigation.html %} + {% elsif root == 'common-tasks' %} + {% include asides/common_tasks_navigation.html %} {% elsif root == 'cookbook' %} {% include asides/cookbook_navigation.html %} {% elsif root == 'lovelace' %} @@ -31,6 +35,16 @@ {% include asides/recent_posts.html %} {% endif %} {% endif %} + {% if page.toc %} + {%- unless page.no_toc -%} +
      +
      +

      On this page

      + {{ content | toc_only }} +
      +
      + {%- endunless -%} + {% endif %}