On this page
- {% toc %} - {%- endunless -%} diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html index f70674aa17c..632e1dd4461 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 /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 %}
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 @@
+
+ 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++Installation
+ {{ content | toc_only }} +
@@ -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 @@ + + +++ diff --git a/source/_includes/installation/container.md b/source/_includes/installation/container.md new file mode 100644 index 00000000000..aca5741b94b --- /dev/null +++ b/source/_includes/installation/container.md @@ -0,0 +1,141 @@ +## 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. + +{{ include.step }}
+ {% include assets/chevron_right.html %} ++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-homeassistant:stable" %} + +#### Raspberry pi 4 + + {% include installation/container/cli.md image="homeassistant/raspberrypi4-homeassistant:stable" %} + +{% elsif page.installation_type == 'alternative' %} + {% include installation/container/alternative.md %} + +{% else %} + {% include installation/container/cli.md image="homeassistant/home-assistant:stable" %} +{% endif %} + +Once the Home Assistant Container is running Home Assistant should be accessible using `http://:8123` (replace with the hostname or IP of the system). You can continue with onboarding. + +{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} + +### 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-homeassistant:stable" %} + +#### Raspberry pi 4 + + {% include installation/container/compose.md image="homeassistant/raspberrypi4-homeassistant: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 + +[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+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..2fb9d251345 --- /dev/null +++ b/source/_includes/installation/operating_system.md @@ -0,0 +1,195 @@ +## 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" + + +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" + +6. Balena Etcher will now download the image, when that is done click "Select target" + +7. Select the {{site.installation.types[page.installation_type].installation_media}} you want to use for your {{site.installation.types[page.installation_type].board}} + +8. Click on "Flash!" to start writing the image + +9. When Balena Etcher is finished writing the image you will get this confirmation + + +### 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 %} + +### Start up your Virtual Machine + +1. Start the Virtual Machine +2. Observe the boot process of Home Assistant Operating System +3. Once completed 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). + +{% endif %} + +{% endif %} + +With the Home Assistant Operating System installed and accessible you can continue with onboarding. + +{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} + + +[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..cf23481752d --- /dev/null +++ b/source/_includes/installation/supervised.md @@ -0,0 +1,16 @@ +## 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. + +Once the Home Assistant Supervised installation is running and Home Assistant accessible you can continue with onboarding. + +{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} \ No newline at end of file diff --git a/source/_includes/javascripts/scripts.html b/source/_includes/javascripts/scripts.html index 79868bc88da..11175b4acd0 100644 --- a/source/_includes/javascripts/scripts.html +++ b/source/_includes/javascripts/scripts.html @@ -11,11 +11,12 @@ s.parentNode.insertBefore(g,s)}(document,'script')); + +## Got a tip for the next edition? + +Have you seen (or made) something awesome, interesting, unique, amazing, inspirational, unusual or funny, using Home Assistant? + +[Click here to send us your Community Highlight suggestion](/suggest-community-highlight). + +Also, don't forget to share your creations with us via Social Media: + +- Twitter it! Be sure to mention [@home_assistant][twitter] +- Share it on our [Facebook group][facebook-group] +- Post it to our [subreddit][reddit] +- Tag [@homeasssistant][instagram] on Instagram +- Or via chat, drop us a line in the [#lounge at Discord][chat] + +See you next edition! + +[chat]: https://www.home-assistant.io/join-chat +[facebook-group]: https://www.facebook.com/groups/HomeAssistant/ +[instagram]: https://www.instagram.com/homeassistant/ +[reddit]: https://www.reddit.com/r/homeassistant +[twitter]: https://www.twitter.com/home_assistant \ No newline at end of file diff --git a/source/_redirects b/source/_redirects index 4c36b49e843..0c24daf7807 100644 --- a/source/_redirects +++ b/source/_redirects @@ -2081,9 +2081,9 @@ /getting-started/scripts-service-calls /docs/scripts/service-calls /getting-started/scripts-conditions /docs/scripts/conditions /getting-started/securing /docs/configuration/securing -/getting-started/troubleshooting /docs/installation/troubleshooting -/getting-started/troubleshooting-configuration /docs/configuration/troubleshooting -/getting-started/updating /docs/installation/updating +/getting-started/troubleshooting /docs/troubleshooting +/getting-started/troubleshooting-configuration /docs/troubleshooting +/getting-started/updating /common-tasks/os /getting-started/yaml /docs/configuration/yaml /getting-started/z-wave /docs/z-wave /getting-started/z-wave-devices /docs/z-wave/devices @@ -2098,6 +2098,21 @@ /topics/splitting_configuration /docs/configuration/splitting_configuration /topics/state_object /docs/configuration/state_object /topics/templating /docs/configuration/templating +/common-tasks /common-tasks/os +/docs/installation /installation +/docs/installation/docker /installation +/docs/installation/raspberry-pi /installation +/docs/installation/updating /common-tasks/os +/docs/installation/virtualenv /installation +/hassio /getting-started +/hassio/commandline /common-tasks/os#home-assistant-via-the-command-line +/hassio/enable_i2c /common-tasks/os#enable-i2c +/hassio/flashing_n2_otg /common-tasks/os#flashing-an-odroid-n2 +/hassio/haos_common_tasks /common-tasks/os +/hassio/hassos_faq /faq +/hassio/index /installation +/hassio/installation /installation +/hassio/installing_third_party_addons /common-tasks/os#installing-third-party-add-ons # Migrated Community Guides /cookbook/apache_configuration https://community.home-assistant.io/t/reverse-proxy-with-apache/196942 @@ -2170,6 +2185,8 @@ /integrations/lovelace /lovelace # Removed documentation +/docs/installation /getting-started +/docs/installation/dokcer /getting-started /docs/installation/hassbian /getting-started /docs/installation/macos /docs/installation/virtualenv /docs/installation/raspberry-pi-all-in-one /getting-started @@ -2265,4 +2282,3 @@ /components/sensor.crimereports /more-info/removed-integration 301 /components/crimereports /more-info/removed-integration 301 /integrations/crimereports /more-info/removed-integration 301 - diff --git a/source/common-tasks/container.markdown b/source/common-tasks/container.markdown new file mode 100644 index 00000000000..5a4d3032371 --- /dev/null +++ b/source/common-tasks/container.markdown @@ -0,0 +1,10 @@ +--- +title: "Common Tasks" +description: "Common tasks for Home Assistant Container" +installation: container +--- +{% include common-tasks/update.md %} +{% include common-tasks/specific_version.md %} +{% include common-tasks/beta_version.md %} +{% include common-tasks/development_version.md %} +{% include common-tasks/configuration_check.md %} diff --git a/source/common-tasks/core.markdown b/source/common-tasks/core.markdown new file mode 100644 index 00000000000..b9a993e68f1 --- /dev/null +++ b/source/common-tasks/core.markdown @@ -0,0 +1,10 @@ +--- +title: "Common Tasks" +description: "Common tasks for Home Assistant Core" +installation: core +--- +{% include common-tasks/update.md %} +{% include common-tasks/specific_version.md %} +{% include common-tasks/beta_version.md %} +{% include common-tasks/development_version.md %} +{% include common-tasks/configuration_check.md %} diff --git a/source/common-tasks/os.markdown b/source/common-tasks/os.markdown new file mode 100644 index 00000000000..ab837046960 --- /dev/null +++ b/source/common-tasks/os.markdown @@ -0,0 +1,21 @@ +--- +title: "Common Tasks" +description: "Common tasks for Home Assistant Operating System" +installation: os +installation_name: "Operating System" +--- +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. + +{% include common-tasks/update.md %} +{% include common-tasks/specific_version.md %} +{% include common-tasks/beta_version.md %} +{% include common-tasks/development_version.md %} +{% include common-tasks/configuration_check.md %} +{% include common-tasks/file_access.md %} +{% include common-tasks/snapshots.md %} +{% include common-tasks/commandline.md %} +{% include common-tasks/lost_password.md %} +{% include common-tasks/third-party-addons.md %} +{% include common-tasks/flashing_n2_otg.md %} +{% include common-tasks/enable_i2c.md %} + diff --git a/source/common-tasks/supervised.markdown b/source/common-tasks/supervised.markdown new file mode 100644 index 00000000000..5fdf4837797 --- /dev/null +++ b/source/common-tasks/supervised.markdown @@ -0,0 +1,16 @@ +--- +title: "Common Tasks" +description: "Common tasks for Home Assistant Supervised" +installation: supervised +installation_name: Supervised +--- +{% include common-tasks/update.md %} +{% include common-tasks/specific_version.md %} +{% include common-tasks/beta_version.md %} +{% include common-tasks/development_version.md %} +{% include common-tasks/configuration_check.md %} +{% include common-tasks/file_access.md %} +{% include common-tasks/snapshots.md %} +{% include common-tasks/commandline.md %} +{% include common-tasks/lost_password.md %} +{% include common-tasks/third-party-addons.md %} \ No newline at end of file diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown index 67082f494f9..81534f1ba2a 100644 --- a/source/getting-started/automation.markdown +++ b/source/getting-started/automation.markdown @@ -49,4 +49,4 @@ Further reading on automations: - [Conditions](/docs/automation/condition/) - [Actions](/docs/automation/action/) -### [Next step: Presence detection »](/getting-started/presence-detection/) +{% include getting-started/next_step.html step="Presence detection" link="/getting-started/presence-detection/" %} diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index caa54501b15..ea581daa125 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -1,86 +1,13 @@ --- -title: "Install Home Assistant" -description: "Getting started: How to install Home Assistant." +title: "Getting Started" +description: "Getting started with Home Assistant" +body_id: getting_started +show_title: true --- -{% comment %} - -Note for contributors: - -The getting started guide aims at getting new users get Home Assistant up and -running as fast as possible. Nothing else. All other things should not be -written down, as it creates a spaghetti of links and the user will lose focus. - -So here are guidelines: - - - Focus on the bare necessities. No remote port, no securing installation. The - defaults are good enough to get a system up and running for the first guide. - - Avoid or explain technical terms. - - Do not talk about YAML if it can be partially/fully done in UI. - - Do not tell people about stuff they can do later. This can be added to a - 2nd tier guide. - - The first page of the guide is for installation, hence Home Assistant specific. - Other pages should not refer to it except for the page introducing the last - page that introduces `configuration.yaml`. - -{% endcomment %} - -This guide will help you get Home Assistant running on a Raspberry Pi, turning your Raspberry Pi into the ultimate home automation hub. - -Follow this guide if you want to get started with Home Assistant easily or if you have little to no Linux experience. For advanced users (or if you don't have a [device that is supported by this guide][supported]), check out our [alternative installation methods](/docs/installation/). Once you finish your alternative installation, you can continue at the [next step][next-step]. - -[supported]: /hassio/installation/ - -### Suggested hardware - -We will need a few things to get started with installing Home Assistant. The Raspberry Pi 4 Model B is a good, affordable starting point for your home automation journey. 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. - -- [Raspberry Pi 4 Model B (2GB)](https://amzn.to/2XULT2z) + [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/sd-standard-overview/application-performance-class/) 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. - -### Software requirements - -- Download and extract the Home Assistant image for [your device](/hassio/installation/). -- Download [balenaEtcher] to write the image to an SD card. - -[balenaEtcher]: https://www.balena.io/etcher - -### Installation - -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. -4. The most reliable networking setup for your Raspberry Pi is to connect it using an Ethernet cable; however, if you want to configure Wi-Fi or a static IP address (this step requires a USB stick) you can try this: - - Format a USB stick to FAT32 with the volume name `CONFIG`. - - Create a folder named `network` in the root of the newly-formatted USB stick. - - Within that folder, create a file named `my-network` without a file extension. - - Copy one of [the examples] to the `my-network` file and adjust accordingly. - - Plug the USB stick into the Raspberry Pi. - -5. Insert the SD card into your Raspberry Pi. If you are going to use an Ethernet cable, connect that too. -6. Connect your power supply to the Raspberry Pi. -7. The Raspberry Pi will now boot up, connect to the Internet and download the latest version of Home Assistant. This will take about 20 minutes. -8. On another computer, navigate to `http://homeassistant.local:8123` to access Home Assistant. If you are running an older Windows version or have a stricter network configuration, you might need to access Home Assistant at `http://homeassistant:8123` or `http://X.X.X.X:8123` (replace `X.X.X.X` with your Pi's IP address). - --
- -9. If you used a USB stick for configuring the network, you can now remove it. - -[the examples]: https://github.com/home-assistant/hassos/blob/dev/Documentation/network.md - -
-As the installation process does its thing your screen should look like this (may take a few minutes to load after the Raspberry Pi boots)
-- - The Raspberry Pi will not show a user interface for Home Assistant if you connect a display. You need to use another computer to access Home Assistant. - -- -### [Next step: Onboarding »][next-step] - -[next-step]: /getting-started/onboarding/ - -_As an Amazon Associate Home Assistant earns from qualifying purchases._ +{% include getting-started/next_step.html step="Installation" link="/installation/" %} +{% include getting-started/next_step.html step="Onboarding" link="/getting-started/onboarding/" %} +{% include getting-started/next_step.html step="Automation" link="/getting-started/automation/" %} +{% include getting-started/next_step.html step="Presence detection" link="/getting-started/presence-detection/" %} +{% include getting-started/next_step.html step="Join the community" link="/getting-started/join-the-community/" %} +{% include getting-started/next_step.html step="Advanced Configuration" link="/getting-started/configuration/" %} diff --git a/source/getting-started/onboarding.markdown b/source/getting-started/onboarding.markdown index ef18296b8c8..35a2a6f45e2 100644 --- a/source/getting-started/onboarding.markdown +++ b/source/getting-started/onboarding.markdown @@ -44,4 +44,4 @@ When each integration is done setting up, it will ask you to put the new devices When you're done, navigate back to the web interface and voila, your devices are ready for you to control. -### [Next step: Automate Home Assistant »](/getting-started/automation/) +{% include getting-started/next_step.html step="Automate Home Assistant" link="/getting-started/automation/" %} diff --git a/source/getting-started/presence-detection.markdown b/source/getting-started/presence-detection.markdown index 24243b20192..24fa32cd509 100644 --- a/source/getting-started/presence-detection.markdown +++ b/source/getting-started/presence-detection.markdown @@ -47,4 +47,4 @@ The map view will hide all devices that are home. [ha-map]: /integrations/map/ [companion]: https://companion.home-assistant.io/ -### [Next step: Join the Community »](/getting-started/join-the-community/) +{% include getting-started/next_step.html step="Join the Community" link="/getting-started/join-the-community/" %} diff --git a/source/hassio/hassos_faq.markdown b/source/hassio/hassos_faq.markdown deleted file mode 100644 index 8d4c577008a..00000000000 --- a/source/hassio/hassos_faq.markdown +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "Home Assistant OS FAQ" -description: "Frequently Asked Questions for Home Assistant OS" ---- -## Is USB Boot for the Raspberry Pi 4 supported? - -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. - -## Is the Raspberry Pi 4 with 8GB RAM supported? - -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. - -## How do I run a specific version of Home Assistant? - -For this you would need to install the [Terminal & SSH add-on][ssh] or use the console -that is available on your device by connecting a keyboard and screen. - -To install the Terminal & SSH add-on, choose **Supervisor**, which is located in the sidebar and then the add-on store. If you don't see it, enable "Advanced Mode" from your profile page. - -Use the web-based terminal or SSH to your Home Assistant system, or connect to the console, and run: - -```bash -ha core update --version=0.XX.X -``` - -Replace 0.XX.X with the version you want. e.g., `0.111.2` - -You can also use a similar command for the operating system: - -```bash -ha os update --version 4.11 -``` - -## Do I need to leave the USB stick connected for Wi-Fi? - -No. The USB "CONFIG" stick is only used to import a network profile to `/etc/NetworkManager/system-connections/` and can be removed. - -## 404 Client Error: Not Found ("no such image: homeassistant/...) - -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. - -## Why does the start button for an add-on flash red when I click it? - -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. - -## I'm trying to find my files on the host or SD card. Where are they? - -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/`. diff --git a/source/hassio/index.markdown b/source/hassio/index.markdown deleted file mode 100644 index 298110c7a08..00000000000 --- a/source/hassio/index.markdown +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Home Assistant" -description: "Manage your Home Assistant and custom add-ons." ---- - -Home Assistant turns your Raspberry Pi (or another device) into the ultimate home automation hub. With Home Assistant, you can focus on integrating your devices and writing automations. - -[Go to the installation instructions »][install] - -The advantages of using Home Assistant: - -- Free and open source -- Optimized for embedded devices like Raspberry Pi -- 100% local home automation -- Easy installation and updates (powered by the [Home Assistant Operating System] and [Home Assistant Core]) -- Management web interface integrated into Home Assistant -- Create and restore full backups of your whole configuration with ease -- Install many popular add-ons with a single click! For example [Google Assistant], encryption via [Let's Encrypt] and dynamic DNS via [Duck DNS].
[Browse available add-ons »][all]
-- Active community that is helpful and sharing add-ons including AppDaemon, Homebridge and InfluxDB.
[Browse the forums »][forums]
[Join the Home Assistant chat »][chat]
[Browse community add-on repositories »][comm-add-ons]
- -- -- -### Upgrading - -Home Assistant users can update via the 'Supervisor' panel in the UI when a new version is released. - --
- -[google assistant]: /addons/google_assistant/ -[snips.ai]: /addons/snips/ -[let's encrypt]: /addons/lets_encrypt/ -[duck dns]: /addons/duckdns/ -[forums]: https://community.home-assistant.io/c/hass-io -[comm-add-ons]: https://community.home-assistant.io/tags/hassio-repository -[all]: /addons/ -[chat]: https://discord.gg/K3UVxJd -[home assistant operating system]: https://github.com/home-assistant/operating-system -[home assistant core]: https://www.home-assistant.io/docs/installation/ -[install]: /hassio/installation/ diff --git a/source/hassio/installation.markdown b/source/hassio/installation.markdown deleted file mode 100644 index aaf7ba01e3c..00000000000 --- a/source/hassio/installation.markdown +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: "Installing Home Assistant OS" -description: "Instructions on how to install Home Assistant OS." ---- - -The following will take you through the steps required to install Home Assistant OS. - -1. Download the appropriate install option: - - - As an image for your device: - - - [Raspberry Pi 3 Model B and B+ 32-bit][pi3-32] - - [Raspberry Pi 3 Model B and B+ 64-bit][pi3-64] - - [Raspberry Pi 4 Model B (1 GB, 2 GB and 4 GB model) 32-bit][pi4-32] - - [Raspberry Pi 4 Model B (1 GB, 2 GB, 4 GB and 8 GB model) 64-bit][pi4-64] (64-bit is required for 8 GB model) - - [Tinkerboard][tinker] - - [Odroid-C2][odroid-c2], [Odroid-C4][odroid-c4], [Odroid-N2][odroid-n2], [Odroid-XU4][odroid-xu4] - - [Guide: Flashing Odroid-N2 using OTG-USB][otg-usb] - - [Intel NUC][intel-nuc] - - - As a virtual appliance (x86_64/UEFI): - - - [VMDK][vmdk], [VHDX][vhdx], [VDI][vdi], [QCOW2][qcow2], [OVA][Virtual Appliance] - -2. Install Home Assistant OS: - - - **For the device images:** Flash the downloaded image to an SD card using [balenaEtcher][balenaEtcher]. If using a Pi, we recommend at least a 32 GB SD card to avoid running out of space. - - **For the virtual appliance images:** 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) - - For VirtualBox create a new virtual machine, select "Other Linux (64Bit), assign it at least 2 GB of memory and "Use an existing virtual hard disk file", select the VDI file from above, afterwards edit the "Settings" of the VM and go "System" then Motherboard and Enable EFI, then "Network" "Adapter 1" Bridged and your adapter. - - For Hyper-V download the VHDX file and unpack it using 7-Zip. Create a new virtual machine, select "Generation 2", assign it at least 2 GB of memory and select "Connection -> "Your Virtual Switch that is bridged", then "Use an existing virtual hard disk" and select the upacked VHDX file. After creation go to "Settings" -> "Security" and deselect "Enable Secure Boot". - - For KVM download the QCOW2 file and unpack it using `unxz`. Create a new virtual machine in `virt-manager`, select "Import existing disk image", provide the path to the unpacked QCOW2 image, choose "Generic Default" for the operating system, assign at least 2 GB memory and 1 vCPU, check the box for "Customize configuration before install" and select your bridge under "Network Selection", then under customization select "Overview" -> "Firmware" -> "UEFI x86_64: ...". If you want mDNS and another multicast to work, you'll need to manually edit the XML to add trustGuestRxFilters='yes' to the interfaces tag. See virsh or virt-manager documentation for how to do that. - - For Vmware Workstation download the VMDK file and unpack it using 7-Zip or `unxz`. Create a new virtual machine, select "Custom", make it compatible with the default of Workstation and ESX, Choose "I will install the operating system later", select "Linux" -> "Other Linux 5.x or later kernel 64-bit", give it at least 2 GB RAM and 1vCPU, select "Use Bridged Networking" then "Use an existing virtual disk" and select the unpacked VMDK file, after creation of VM go to "Settings" and "Options" then "Advanced" and select "Firmware type" to "UEFI". - - For Proxmox, create a new virtual machine, and make note of the VM ID. Under "OS", select "Do not use any media". Under "System" select "Advanced" and change "BIOS" to "OVMF (UEFI)", then select a storage location for the EFI disk. Under "Hard Disk", create a default hard disk (we will delete this later). Set your CPU, memory, and network as needed. From the command line (as root on the Proxmox host), download the qcow2 image with `wget` or `curl` and decompress it (`unxz hassos_ova-5.10.qcow2.xz`). Then, import the disk to your VM, changing the VM ID as needed (`qm importdisk ### hassos_ova-5.10.qcow2 local-lvm --format qcow2`). After you see `Successfully imported disk`, you can remove the qcow2 image (`rm hassos_ova-5.10.qcow2`). Back in the web UI, navigate to your VM, then "Hardware" and locate the default hard disk we created earlier (probably called `disk0`). Click on it, then click "Detach", then click on the disk again and click "Remove" (this should leave you with two disks: the EFI disk and the imported qcow2 disk). Click on the qcow2 disk (probably called `disk2`) and click "Edit" then "Add". Click on the qcow2 disk one last time, then click on "Resize disk" and set your size (Home Assistant will fill up this entire space). - - For VMware ESXi/vSphere installation use the "E1001" or "E1001E" virtual network adapater. There are confirmed mDNS/Multicast discovery issues when using VMware's "VMXnet3" virtual network adapter. - -3. Optional - set up the Wi-Fi or a static IP address. There are two possible places for that: - - on a blank USB stick with a FAT32 partition having partition label `CONFIG`, while in its root directory, create the `network/my-network` file, or - - on the Home Assistant SD card's first, bootable partition (labeled `hassos-boot`, might not be auto mounted in Linux) create the `CONFIG/network/my-network` file. - - For the content of this file, follow the [Home Assistant Operating System howto][hassos-network]. - -4. For image-based installs insert the SD card (and optional USB stick) into the device. - -5. Turn on your device or virtual appliance. On first boot, it downloads the latest version of Home Assistant which takes around 20 minutes (slower/faster depending on the platform and your Internet connection). - -
-Home Assistant dashboard with upgrade notification (under the hamburger menu -> Supervisor)
-
-
-6. You will be able to reach your installation at `http://homeassistant.local:8123` (if your router supports mDNS, otherwise see below).
-
-7. From here, you have two options - either configure your Home Assistant from scratch, or restore a saved snapshot with all its settings and add-ons that you saved in the past.
-
-- -We used `hassio.local` in the past, if you have a system that is installed before this naming change, you might need to use `hassio.local` instead of `homeassistant.local`. - -- -- -If your router doesn't support mDNS, then you'll have to use the IP address of your Pi instead of `homeassistant.local`. For example, `http://192.168.0.9:8123`. You should be able to find the IP address of your Pi from the admin interface of your router. - -- -- -If you are using a Raspberry Pi please remember to ensure you're using an [appropriate power supply][pi-power] with your Pi. Mobile chargers may not be suitable since some were only designed to provide just enough power to the device it was designed for by the manufacturer. **Do not** try to power the Pi from the USB port on a TV, computer, or similar. - -- -Now you can [configure][configure] your install. - -## Updating a 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. Select _Dashboard_ from the _Supervisor_ menu, and then select _Update_. - -## Run a specific version of Home Assistant - -For this you would need to install the [Terminal & SSH add-on][ssh] or use the console -that is available on your device by connecting a keyboard and screen. - -To install the Terminal & SSH add-on, choose **Supervisor**, which is located in the sidebar and then the add-on store. - -Use the web-based terminal or SSH to your Home Assistant system, or connect to the console, and run: - -```bash -ha core update --version=X.Y.Z -``` - -Replacing `X.Y.Z` with your desired version (i.e., `2020.12.0` or `0.118.5`). - -## Run the beta version of Home Assistant - -If you would like to test next release before anyone else, you can install the beta version released every month: - -1. Backup your installation, using the snapshot functionality Home Assistant offers. -2. Check the [Home Assistant Beta release notes](https://rc.home-assistant.io/latest-release-notes/) for breaking changes. 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. Select _System_ tab from the _Supervisor_ menu, then select _Join Beta Channel_ under _Supervisor_, then select _Reload_. -4. Select _Dashboard_ tab from the _Supervisor_ menu, and then select _Update_. - - -[balenaEtcher]: https://www.balena.io/etcher -[hassos-network]: https://github.com/home-assistant/operating-system/blob/dev/Documentation/network.md -[pi3-32]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_rpi3-5.10.img.xz -[pi3-64]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_rpi3-64-5.10.img.xz -[pi4-32]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_rpi4-5.10.img.xz -[pi4-64]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_rpi4-64-5.10.img.xz -[tinker]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_tinker-5.10.img.xz -[odroid-c2]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_odroid-c2-5.10.img.xz -[odroid-c4]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_odroid-c4-5.10.img.xz -[odroid-n2]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_odroid-n2-5.10.img.xz -[odroid-xu4]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_odroid-xu4-5.10.img.xz -[intel-nuc]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_intel-nuc-5.10.img.xz -[vmdk]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_ova-5.10.vmdk.xz -[vhdx]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_ova-5.10.vhdx.xz -[vdi]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_ova-5.10.vdi.xz -[qcow2]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_ova-5.10.qcow2.xz -[Virtual Appliance]: https://github.com/home-assistant/operating-system/releases/download/5.10/hassos_ova-5.10.ova -[local]: http://homeassistant.local:8123 -[samba]: /addons/samba/ -[ssh]: /addons/ssh/ -[pi-power]: https://www.raspberrypi.org/help/faqs/#powerReqs -[configure]: /getting-started/configuration/ -[otg-usb]: /hassio/flashing_n2_otg/ diff --git a/source/images/blog/2021-02-12-community-highlights/esphome.png b/source/images/blog/2021-02-12-community-highlights/esphome.png new file mode 100644 index 00000000000..f1a71fd0f79 Binary files /dev/null and b/source/images/blog/2021-02-12-community-highlights/esphome.png differ diff --git a/source/images/blog/2021-02-12-community-highlights/social.png b/source/images/blog/2021-02-12-community-highlights/social.png new file mode 100644 index 00000000000..dd69b5d47c8 Binary files /dev/null and b/source/images/blog/2021-02-12-community-highlights/social.png differ diff --git a/source/images/blog/2021-02-12-community-highlights/streamdeck.png b/source/images/blog/2021-02-12-community-highlights/streamdeck.png new file mode 100644 index 00000000000..25701859736 Binary files /dev/null and b/source/images/blog/2021-02-12-community-highlights/streamdeck.png differ diff --git a/source/images/installation/etcher1.png b/source/images/installation/etcher1.png new file mode 100644 index 00000000000..b182a11ff27 Binary files /dev/null and b/source/images/installation/etcher1.png differ diff --git a/source/images/installation/etcher2.png b/source/images/installation/etcher2.png new file mode 100644 index 00000000000..6818dc7137c Binary files /dev/null and b/source/images/installation/etcher2.png differ diff --git a/source/images/installation/etcher3.png b/source/images/installation/etcher3.png new file mode 100644 index 00000000000..9b5e1ba643d Binary files /dev/null and b/source/images/installation/etcher3.png differ diff --git a/source/images/installation/etcher4.png b/source/images/installation/etcher4.png new file mode 100644 index 00000000000..c772c6b61af Binary files /dev/null and b/source/images/installation/etcher4.png differ diff --git a/source/images/installation/etcher5.png b/source/images/installation/etcher5.png new file mode 100644 index 00000000000..d7fe45eea61 Binary files /dev/null and b/source/images/installation/etcher5.png differ diff --git a/source/images/installation/etcher6.png b/source/images/installation/etcher6.png new file mode 100644 index 00000000000..ac0729bf0c4 Binary files /dev/null and b/source/images/installation/etcher6.png differ diff --git a/source/images/installation/intel-nuc.svg b/source/images/installation/intel-nuc.svg new file mode 100644 index 00000000000..129840103d3 --- /dev/null +++ b/source/images/installation/intel-nuc.svg @@ -0,0 +1,32 @@ + + + + diff --git a/source/images/installation/linux.png b/source/images/installation/linux.png new file mode 100644 index 00000000000..3267f340769 Binary files /dev/null and b/source/images/installation/linux.png differ diff --git a/source/images/installation/odroid.png b/source/images/installation/odroid.png new file mode 100644 index 00000000000..4b89913a6c6 Binary files /dev/null and b/source/images/installation/odroid.png differ diff --git a/source/images/installation/tinkerboard.png b/source/images/installation/tinkerboard.png new file mode 100644 index 00000000000..3ad8db7ece1 Binary files /dev/null and b/source/images/installation/tinkerboard.png differ diff --git a/source/images/more-info/system_health.png b/source/images/more-info/system_health.png new file mode 100644 index 00000000000..46e38366209 Binary files /dev/null and b/source/images/more-info/system_health.png differ diff --git a/source/images/more-info/system_health_github.png b/source/images/more-info/system_health_github.png new file mode 100644 index 00000000000..3763d09781a Binary files /dev/null and b/source/images/more-info/system_health_github.png differ diff --git a/source/installation/alternative.markdown b/source/installation/alternative.markdown new file mode 100644 index 00000000000..efcc59b2c13 --- /dev/null +++ b/source/installation/alternative.markdown @@ -0,0 +1,17 @@ +--- +title: "Alternative" +description: "Install Home Assistant" +installation_type: alternative +--- +{% comment %} +Included sections for this page is located under source/_includes/installation +{% endcomment %} + +{% include installation/operating_system.md %} +{% include installation/container.md %} + +## 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/installation/index.html b/source/installation/index.html new file mode 100644 index 00000000000..d4582f13cd0 --- /dev/null +++ b/source/installation/index.html @@ -0,0 +1,235 @@ +--- +title: "Installation" +description: "Install Home Assistant" +body_id: getting_started +show_title: true +toc: true +--- + + +++ ++ Home Assistant offers four different installation methods. We recommend one of the following two: +
+-
+
- Home Assistant Operating System: Minimal Operating System optimized to power Home Assistant. + Comes with Supervisor to manage Home Assistant Core and add-ons pre-installed. Recommended installation type. +
- Home Assistant Container: Standalone container-based installation of Home Assistant Core (e.g. Docker). +
In addition there are two installation methods available for experienced users:
+-
+
- Home Assistant Supervised: Manual installation of the Supervisor. +
- Home Assistant Core: Manual installation using a Python virtual environment. +
+ The list below shows which installation method is available on what device or platform. +
++ We recommend a dedicated system to run Home Assistant. If you are unsure what to choose, using a + Raspberry Pi and the Home Assistant Operating System is a good start. +
+ ++ If you are using the Home Assistant Blue, the Home Assistant Operating System is + already preinstalled. You can skip this installation step. +
++ ++ +ODROID
+ +++ + +++ {% include assets/chevron_right.html %} +++
+ + ODROID ++-
+
- Home Assistant Operating System +
- Home Assistant Container +
- Home Assistant Core +
Raspberry Pi
+ +++ + +++ {% include assets/chevron_right.html %} ++ +++ Raspberry Pi ++-
+
- Home Assistant Operating System +
- Home Assistant Container +
- Home Assistant Core +
ASUS Tinkerboard
+ +++ + +++ {% include assets/chevron_right.html %} +++
+ + ASUS Tinkerboard ++-
+
- Home Assistant Operating System +
- Home Assistant Container +
- Home Assistant Core +
Intel NUC
+ +++ + +++ {% include assets/chevron_right.html %} +++
+ + Intel NUC ++-
+
- Home Assistant Operating System +
- Home Assistant Container +
- Home Assistant Core +
Windows
+ +++ + +++ {% include assets/chevron_right.html %} ++ +++ Windows ++-
+
- Home Assistant Operating System (VM) +
- Home Assistant Core +
macOS
+ +++ + +++ {% include assets/chevron_right.html %} ++ +++ macOS ++-
+
- Home Assistant Operating System (VM) +
- Home Assistant Core +
Linux
+ +++ + +++ {% include assets/chevron_right.html %} +++
+ + Linux ++-
+
- Home Assistant Operating System (VM) +
- Home Assistant Container +
- Home Assistant Core +
- Home Assistant Supervised +
Alternative
+ +++ + +++ {% include assets/chevron_right.html %} ++ +++ Alternative ++VM's not covered by other categories, NAS installations and community guides
+Compare Installation Methods
+ ++
+ +{% include getting-started/next_step.html step="onboarding" link="/getting-started/onboarding" %} diff --git a/source/installation/linux.markdown b/source/installation/linux.markdown new file mode 100644 index 00000000000..17e431cb8e5 --- /dev/null +++ b/source/installation/linux.markdown @@ -0,0 +1,13 @@ +--- +title: "Linux" +description: "Install Home Assistant on a Linux" +installation_type: linux +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% include installation/operating_system.md %} +{% include installation/container.md %} +{% include installation/core.md %} +{% include installation/supervised.md %} diff --git a/source/installation/macos.markdown b/source/installation/macos.markdown new file mode 100644 index 00000000000..4146c8f7e84 --- /dev/null +++ b/source/installation/macos.markdown @@ -0,0 +1,11 @@ +--- +title: "MacOS" +description: "Install Home Assistant on a MacOS" +installation_type: macos +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% include installation/operating_system.md %} +{% include installation/core.md %} diff --git a/source/installation/nuc.markdown b/source/installation/nuc.markdown new file mode 100644 index 00000000000..dac96c15fa6 --- /dev/null +++ b/source/installation/nuc.markdown @@ -0,0 +1,12 @@ +--- +title: "Intel NUC" +description: "Install Home Assistant on Intel NUC" +installation_type: nuc +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% include installation/operating_system.md %} +{% include installation/container.md %} +{% include installation/core.md %} diff --git a/source/installation/odroid.markdown b/source/installation/odroid.markdown new file mode 100644 index 00000000000..0360ea9d043 --- /dev/null +++ b/source/installation/odroid.markdown @@ -0,0 +1,12 @@ +--- +title: "ODROID" +description: "Install Home Assistant on a ODROID" +installation_type: odroid +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% include installation/operating_system.md %} +{% include installation/container.md %} +{% include installation/core.md %} diff --git a/source/installation/raspberrypi.markdown b/source/installation/raspberrypi.markdown new file mode 100644 index 00000000000..a660fa18ad2 --- /dev/null +++ b/source/installation/raspberrypi.markdown @@ -0,0 +1,21 @@ +--- +title: "Raspberry Pi" +description: "Install Home Assistant on a Raspberry Pi" +installation_type: raspberrypi +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% assign board = "Raspberry Pi" %} +{% assign installation_media = "SD card" %} + +OS Container Core Supervised ++ +Automations +โ โ โ โ ++ +Lovelace +โ โ โ โ ++ +Integrations +โ โ โ โ ++ +Blueprints +โ โ โ โ ++ +Uses container +โ โ โ โ ++ +Add-ons +โ โ โ โ ++ +Snapshots +โ โ โ โ ++ +Managed OS +โ โ โ โ ++ +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. + ++ +{% include installation/operating_system.md %} +{% include installation/container.md %} +{% include installation/core.md %} diff --git a/source/installation/tinkerboard.markdown b/source/installation/tinkerboard.markdown new file mode 100644 index 00000000000..af2cbabd5ec --- /dev/null +++ b/source/installation/tinkerboard.markdown @@ -0,0 +1,15 @@ +--- +title: "Asus Tinkerboard" +description: "Install Home Assistant on Asus Tinkerboard" +installation_type: tinkerboard +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% assign board = "ASUS Tinkerboard" %} +{% assign installation_media = "eMMC module/SD card" %} + +{% include installation/operating_system.md %} +{% include installation/container.md %} +{% include installation/core.md %} diff --git a/source/installation/windows.markdown b/source/installation/windows.markdown new file mode 100644 index 00000000000..4aa00dcc732 --- /dev/null +++ b/source/installation/windows.markdown @@ -0,0 +1,11 @@ +--- +title: "Windows" +description: "Install Home Assistant on Windows" +installation_type: windows +--- +{% comment %} +Included sections for this page is located under source/_includes/getting-started/installation +{% endcomment %} + +{% include installation/operating_system.md %} +{% include installation/core.md %} diff --git a/source/more-info/dockerhub-rate-limit.markdown b/source/more-info/dockerhub-rate-limit.markdown index 757dd02a0d1..324731b461a 100644 --- a/source/more-info/dockerhub-rate-limit.markdown +++ b/source/more-info/dockerhub-rate-limit.markdown @@ -37,5 +37,5 @@ _If you do not want to use the UI, this can also be done with the [CLI]_ [docker-rate-limit]: https://docs.docker.com/docker-hub/download-rate-limit/ [dockerhub-signup]: https://hub.docker.com/signup -[unsupported-container]: /more-info/unsupported/container.markdown +[unsupported-container]: /more-info/unsupported/container.md [CLI]: https://github.com/home-assistant/cli diff --git a/source/more-info/system-health.markdown b/source/more-info/system-health.markdown new file mode 100644 index 00000000000..10a047bf65f --- /dev/null +++ b/source/more-info/system-health.markdown @@ -0,0 +1,23 @@ +--- +title: "System Health" +description: "More information about System Health." +--- + +System health is the card on the Information part of the configuration section in the Home Assistant UI. +This provides information about your environment and enabled integrations. + +To find this card first navigate to the Configuration panel, then scroll all +the way to the bottom and select "Info". At the bottom of that page, you will see the System Health card. + + + +## GitHub issues + +GitHub issues often call for the data presented in the System Health. +The Home Assistant UI provides an easy way to get this information. + +In the top-right corner of the System Health card click on the copy icon +and select "For GitHub" this will format the content of the card and place +it on your clipboard so you can easily paste it into a GitHub issue. + +