You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Beginners should check our [getting started guide](/getting-started/) first.
14
+
</p>
12
15
13
16
There are several reasons why it makes sense to run Home Assistant in a virtual environment. A [virtualenv](https://virtualenv.pypa.io/en/latest/) encapsulates all aspect of a Python environment within a single directory tree. That means the Python packages you install for Home Assistant won't interact with the rest of your system and vice-versa. It means a random upgrade for some other program on your computer won't break Home Assistant, and it means you don't need to install Python packages as root.
14
17
15
-
Virtualenvs are pretty easy to setup. This example will walk through one method of setting one up (there are certainly others). We'll be using Debian in this example (as many Home Assistant users are running Raspbian on a Raspberry Pi), but all of the Python related steps should be the same on just about any platform.
18
+
Virtualenvs are pretty easy to setup. We'll be using Debian in this example (as many Home Assistant users are running Raspbian on a Raspberry Pi), but all of the Python related steps should be the same on just about any platform.
16
19
17
-
### {% linkable_title Step 0: Install some dependencies %}
20
+
### {% linkable_title Basic guide %}
21
+
22
+
The basic guide is for testing Home Assistant. Also check the advanced guide for instances used in production.
## {% linkable_title Step 4: Run Home Assistant %}
47
+
48
+
```bash
49
+
$ $HOME/homeassistant/bin/hass
50
+
```
51
+
52
+
### {% linkable_title Advanced guide %}
53
+
## {% linkable_title Separate user & group for Home Assistant (Basic guide step 2) %}
27
54
28
-
This step is optional, but it's a good idea to give services like Home Assistant their own user. It gives you more granular control over permissions, and reduces the exposure to the rest of your system in the event there is a security related bug in Home Assistant. This is a reasonably Linux oriented step, and will look different on other operating systems (or even other Linux distributions).
55
+
It's a good idea to give services like Home Assistant their own user. It gives you more granular control over permissions, and reduces the exposure to the rest of your system in the event there is a security related bug in Home Assistant. This is a reasonably Linux oriented step, and will look different on other operating systems (or even other Linux distributions).
29
56
30
57
```bash
31
58
$ sudo adduser --system homeassistant
32
59
$ sudo addgroup homeassistant
33
60
```
34
61
35
-
Home Assistant stores its configuration in `$HOME/.homeassistant` by default, so in this case, it would be in `/home/homeassistant/.homeassistant`
62
+
Home Assistant stores its configuration in `$HOME/.homeassistant` by default, so in this case, it would be in `/home/homeassistant/.homeassistant`.
36
63
37
-
If you plan to use a Z-Wave controller, you will need to add this user to the `dialout` group
64
+
If you plan to use a Z-Wave controller, you will need to add this user to the `dialout` group:
38
65
39
66
```bash
40
67
$ sudo usermod -G dialout -a homeassistant
41
68
```
42
69
43
-
###{% linkable_title Step 2: Create a directory for Home Assistant %}
70
+
## {% linkable_title Custom installation directory for Home Assistant (Basic guide step 2) %}
44
71
45
-
This can be anywhere you want. We chose to put it in `/srv`. You also need to change the ownership of the directory to the user you created above (if you created one).
72
+
This can be anywhere you want. We chose to put it in `/srv`. You also need to change the ownership of the directory to the user you created above.
###{% linkable_title Step 3: Become the new user %}
80
+
## {% linkable_title Install or update Home Assistant %}
53
81
54
82
This is obviously only necessary if you created a `homeassistant` user, but if you did, be sure to switch to that user whenever you install things in your virtualenv, otherwise you'll end up with mucked up permissions.
55
83
@@ -59,48 +87,21 @@ $ sudo su -s /bin/bash homeassistant
59
87
60
88
The `su` command means 'switch' user. We use the '-s' flag because the `homeassistant` user is a system user and doesn't have a default shell by default (to prevent attackers from being able to log in as that user).
61
89
62
-
### {% linkable_title Step 4: Set up the virtualenv %}
63
-
64
-
All this step does is stick a Python environment in the directory we're using. That's it. It's just a directory. There's nothing special about it, and it is entirely self-contained.
65
-
66
-
It will include a `bin` directory, which will contain all the executables used in the virtualenv (including Home Assistant itself). It also includes a script called `activate` which we will use to activate the virtualenv.
67
-
68
-
```bash
69
-
$ virtualenv -p python3 /srv/homeassistant
70
-
```
71
-
72
-
### {% linkable_title Step 5: Activate the virtualenv %}
73
-
74
90
```bash
75
91
$ source /srv/homeassistant/bin/activate
76
-
```
77
-
78
-
After that, your prompt should include `(homeassistant)`.
79
-
80
-
### {% linkable_title Step 6: Install Home Assistant %}
81
-
82
-
Once your virtualenv has been activated, you don't need to `sudo` any of your `pip` commands. `pip` will be installing things in the virtualenv, which the `homeassistant` user has permission to modify.
And that's it... you now have Home Assistant installed, and you can be sure that every bit of it is contained in `/srv/homeassistant`.
95
+
## {% linkable_title Run Home Assistant (Basic guide step 4) %}
89
96
90
-
### {% linkable_title Finally... Run Home Assistant %}
91
-
92
-
There are two ways to launch Home Assistant. If you are **in** the virtualenv, you can just run `hass` and it will work as normal. If the virtualenv is not activated, you just use the `hass` executable in the `bin` directory mentioned earlier. There is one caveat... Because Home Assistant stores its configuration in the user's home directory, we need to be the user `homeassistant` user or specify the configuration with `-c`.
97
+
There are two ways to launch Home Assistant. If you are **in** the virtualenv, you can just run `hass` and it will work as normal. If the virtualenv is not activated, you just use the `hass` executable in the `bin` directory mentioned earlier. There is one caveat... Because Home Assistant stores its configuration in the user's home directory, we need to be the user `homeassistant` or specify the configuration with `-c`.
The `-H` flag is important. It sets the `$HOME` environment variable to `/home/homeassistant` so `hass` can find its configuration.
99
104
100
-
### {% linkable_title Upgrading Home Assistant %}
101
-
102
-
Upgrading Home Assistant is simple, just repeat steps 3, 5 and 6.
103
-
104
-
### {% linkable_title Starting Home Assistant on boot %}
105
+
## {% linkable_title Starting Home Assistant on boot %}
105
106
106
107
The [autostart instructions](/getting-started/autostart/) will work just fine, just be sure to replace `/usr/bin/hass` with `/srv/homeassistant/bin/hass` and specify the `homeassistant` user where appropriate.
0 commit comments