home-assistant.github.io/docs/installation/virtualenv/index.html
2017-10-29 11:24:55 +00:00

393 lines
24 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9"> <![endif]-->
<!--[if gt IE 8]><!--> <html> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Installation in virtualenv - Home Assistant</title>
<meta name="author" content="Home Assistant">
<meta name="description" content="Instructions how to install Home Assistant in a virtual environment.">
<meta name="viewport" content="width=device-width">
<link rel="canonical" href="https://home-assistant.io/docs/installation/virtualenv/">
<meta property="fb:app_id" content="338291289691179">
<meta property="og:title" content="Installation in virtualenv">
<meta property="og:site_name" content="Home Assistant">
<meta property="og:url" content="https://home-assistant.io/docs/installation/virtualenv/">
<meta property="og:type" content="article">
<meta property="og:description" content="Instructions how to install Home Assistant in a virtual environment.">
<meta property="og:image" content="https://home-assistant.io/images/default-social.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@home_assistant">
<meta name="twitter:title" content="Installation in virtualenv">
<meta name="twitter:description" content="Instructions how to install Home Assistant in a virtual environment.">
<meta name="twitter:image" content="https://home-assistant.io/images/default-social.png">
<link href="/stylesheets/screen.css" media="screen, projection, print" rel="stylesheet">
<link href="/atom.xml" rel="alternate" title="Home Assistant" type="application/atom+xml">
<link rel='shortcut icon' href='/images/favicon.ico' />
<link rel='icon' type='image/png' href='/images/favicon-192x192.png' sizes='192x192' />
</head>
<body >
<header class='site-header'>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item three-tenths lap-two-sixths palm-one-whole ha-title">
<a href="/" class="site-title">
<img width='40' src='/demo/favicon-192x192.png'>
<span>Home Assistant</span>
</a>
</div>
<div class="grid__item seven-tenths lap-four-sixths palm-one-whole">
<nav>
<input type="checkbox" id="toggle">
<label for="toggle" class="toggle" data-open="Main Menu" data-close="Close Menu"></label>
<ul class="menu pull-right">
<li><a href="/getting-started/">Getting started</a></li>
<li><a href="/components/">Components</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/cookbook/">Examples</a></li>
<li><a href="/developers/">Developers</a></li>
<li><a href="/blog/">Blog</a></li>
<li><a href="/help/">Need help?</a></li>
<li><a href='#' class='show-search'><i class="icon-search"></i></a></li>
</ul>
</nav>
<div class='search-container' style='display: none'>
<div class='search'>
<i class="icon-search"></i>
<input id='search' placeholder='Search the docs…'>
<a href='#' class='close'><i class="icon-remove-sign"></i></a>
</div>
</div>
</div>
</div>
</div>
</header>
<div class="grid-wrapper">
<div class="grid grid-center">
<div class="grid__item two-thirds lap-one-whole palm-one-whole">
<article class="page">
<div class='edit-github'><a href='https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_docs/installation/virtualenv.markdown'>Edit this page on GitHub</a></div>
<header>
<h1 class="title indent">
Installation in virtualenv
</h1>
</header>
<hr class="divider">
<p>There are several reasons why it makes sense to run Home Assistant in a virtual environment. A <a href="https://virtualenv.pypa.io/en/latest/">virtualenv</a> encapsulates all aspect of a Python environment within a single directory tree. That means the Python packages you install for Home Assistant wont interact with the rest of your system and vice-versa. It means a random upgrade for some other program on your computer wont break Home Assistant, and it means you dont need to install Python packages as root.</p>
<p>Virtualenvs are pretty easy to setup. This example will walk through one method of setting one up (there are certainly others). Well 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.</p>
<h3><a class="title-link" name="step-0-install-some-dependencies" href="#step-0-install-some-dependencies"></a> Step 0: Install some dependencies</h3>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo apt-get update
<span class="gp">$ </span>sudo apt-get upgrade
<span class="gp">$ </span>sudo apt-get install python3-pip python3-dev
<span class="gp">$ </span>sudo pip3 install --upgrade virtualenv
</code></pre>
</div>
<h3><a class="title-link" name="step-1-create-a-home-assistant-user--group" href="#step-1-create-a-home-assistant-user--group"></a> Step 1: Create a Home Assistant user &amp; group</h3>
<p>This step is optional, but its 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).</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo adduser --system homeassistant
<span class="gp">$ </span>sudo addgroup homeassistant
</code></pre>
</div>
<p>Home Assistant stores its configuration in <code class="highlighter-rouge">$HOME/.homeassistant</code> by default, so in this case, it would be in <code class="highlighter-rouge">/home/homeassistant/.homeassistant</code></p>
<p>If you plan to use a Z-Wave controller, you will need to add this user to the <code class="highlighter-rouge">dialout</code> group</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo usermod -G dialout -a homeassistant
</code></pre>
</div>
<h3><a class="title-link" name="step-2-create-a-directory-for-home-assistant" href="#step-2-create-a-directory-for-home-assistant"></a> Step 2: Create a directory for Home Assistant</h3>
<p>This can be anywhere you want. We chose to put it in <code class="highlighter-rouge">/srv</code>. You also need to change the ownership of the directory to the user you created above (if you created one).</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo mkdir /srv/homeassistant
<span class="gp">$ </span>sudo chown homeassistant:homeassistant /srv/homeassistant
</code></pre>
</div>
<h3><a class="title-link" name="step-3-become-the-new-user" href="#step-3-become-the-new-user"></a> Step 3: Become the new user</h3>
<p>This is obviously only necessary if you created a <code class="highlighter-rouge">homeassistant</code> user, but if you did, be sure to switch to that user whenever you install things in your virtualenv, otherwise youll end up with mucked up permissions.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo su -s /bin/bash homeassistant
</code></pre>
</div>
<p>The <code class="highlighter-rouge">su</code> command means switch user. We use the -s flag because the <code class="highlighter-rouge">homeassistant</code> user is a system user and doesnt have a default shell by default (to prevent attackers from being able to log in as that user).</p>
<h3><a class="title-link" name="step-4-set-up-the-virtualenv" href="#step-4-set-up-the-virtualenv"></a> Step 4: Set up the virtualenv</h3>
<p>All this step does is stick a Python environment in the directory were using. Thats it. Its just a directory. Theres nothing special about it, and it is entirely self-contained.</p>
<p>It will include a <code class="highlighter-rouge">bin</code> directory, which will contain all the executables used in the virtualenv (including Home Assistant itself). It also includes a script called <code class="highlighter-rouge">activate</code> which we will use to activate the virtualenv.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>virtualenv -p python3 /srv/homeassistant
</code></pre>
</div>
<h3><a class="title-link" name="step-5-activate-the-virtualenv" href="#step-5-activate-the-virtualenv"></a> Step 5: Activate the virtualenv</h3>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span><span class="nb">source</span> /srv/homeassistant/bin/activate
</code></pre>
</div>
<p>After that, your prompt should include <code class="highlighter-rouge">(homeassistant)</code>.</p>
<h3><a class="title-link" name="step-6-install-home-assistant" href="#step-6-install-home-assistant"></a> Step 6: Install Home Assistant</h3>
<p>Once your virtualenv has been activated, you dont need to <code class="highlighter-rouge">sudo</code> any of your <code class="highlighter-rouge">pip</code> commands. <code class="highlighter-rouge">pip</code> will be installing things in the virtualenv, which the <code class="highlighter-rouge">homeassistant</code> user has permission to modify.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">(homeassistant)$ </span>pip3 install --upgrade homeassistant
</code></pre>
</div>
<p>And thats it… you now have Home Assistant installed, and you can be sure that every bit of it is contained in <code class="highlighter-rouge">/srv/homeassistant</code>.</p>
<h3><a class="title-link" name="finally-run-home-assistant" href="#finally-run-home-assistant"></a> Finally… Run Home Assistant</h3>
<p>There are two ways to launch Home Assistant. If you are <strong>in</strong> the virtualenv, you can just run <code class="highlighter-rouge">hass</code> and it will work as normal. If the virtualenv is not activated, you just use the <code class="highlighter-rouge">hass</code> executable in the <code class="highlighter-rouge">bin</code> directory mentioned earlier. There is one caveat… Because Home Assistant stores its configuration in the users home directory, we need to be the user <code class="highlighter-rouge">homeassistant</code> user or specify the configuration with <code class="highlighter-rouge">-c</code>.</p>
<div class="language-bash highlighter-rouge"><pre class="highlight"><code><span class="gp">$ </span>sudo -u homeassistant -H /srv/homeassistant/bin/hass
</code></pre>
</div>
<p>The <code class="highlighter-rouge">-H</code> flag is important. It sets the <code class="highlighter-rouge">$HOME</code> environment variable to <code class="highlighter-rouge">/home/homeassistant</code> so <code class="highlighter-rouge">hass</code> can find its configuration.</p>
<h3><a class="title-link" name="upgrading-home-assistant" href="#upgrading-home-assistant"></a> Upgrading Home Assistant</h3>
<p>Upgrading Home Assistant is simple, just repeat steps 3, 5 and 6.</p>
<h3><a class="title-link" name="starting-home-assistant-on-boot" href="#starting-home-assistant-on-boot"></a> Starting Home Assistant on boot</h3>
<p>The <a href="/getting-started/autostart/">autostart instructions</a> will work just fine, just be sure to replace <code class="highlighter-rouge">/usr/bin/hass</code> with <code class="highlighter-rouge">/srv/homeassistant/bin/hass</code> and specify the <code class="highlighter-rouge">homeassistant</code> user where appropriate.</p>
</article>
</div>
<aside id="sidebar" class="grid__item one-third lap-one-whole palm-one-whole">
<div class="grid">
<section class="aside-module grid__item one-whole lap-one-half">
<div class='section'>
<h1 class="title delta">Topics</h1>
<ul class='divided sidebar-menu'>
<li>
<b><a href='/faq/'>FAQ </a></b> |
<b><a href='/docs/glossary/'>Glossary </a></b>
</li>
<li>
<b><a href='/docs/installation/'>Installation </a></b>
<ul>
<li><a href='/hassio/'>Hass.io </a></li>
<li><a class='active' href='/docs/installation/virtualenv/'>Python Virtual Env </a></li>
<li><a href='/docs/installation/hassbian/'>Hassbian </a></li>
<li><a href='/docs/installation/raspberry-pi-all-in-one/'>Raspberry Pi All-in-One </a></li>
<li><a href='/docs/installation/updating/'>Updating </a></li>
<li><a href='/docs/installation/troubleshooting/'>Troubleshooting </a></li>
</ul>
</li>
<li>
<b><a href='/docs/configuration/'>Configuration </a></b>
<ul>
<li><a href='/docs/configuration/yaml/'>YAML </a></li>
<li><a href='/docs/configuration/basic/'>Basic information </a></li>
<li><a href='/docs/configuration/devices/'>Setting up devices </a></li>
<li><a href='/docs/configuration/customizing-devices/'>Customizing entities </a></li>
<li><a href='/docs/configuration/troubleshooting/'>Troubleshooting </a></li>
<li><a href='/docs/configuration/securing/'>Security Check Points </a></li>
</ul>
</li>
<li>
<b>Advanced Configuration</b>
<ul>
<li><a href='/docs/configuration/remote/'>Remote access </a></li>
<li><a href='/docs/configuration/packages/'>Packages </a></li>
<li><a href='/docs/configuration/splitting_configuration/'>Splitting up the configuration </a></li>
<li><a href='/docs/configuration/secrets/'>Storing Secrets </a></li>
<li><a href='/docs/configuration/templating/'>Templating </a></li>
<li><a href='/docs/configuration/group_visibility/'>Group Visibility </a></li>
<li><a href='/docs/configuration/platform_options/'>Entity component platform options </a></li>
</ul>
</li>
<li>
<b>Core objects</b>
<ul>
<li><a href='/docs/configuration/events/'>Events </a></li>
<li><a href='/docs/configuration/state_object/'>State Objects </a></li>
</ul>
</li>
<li>
<b><a href='/docs/automation/'>Automation </a></b>
<ul>
<li><a href='/docs/automation/examples/'>Examples </a></li>
<li><a href='/docs/automation/editor/'>Editor </a></li>
<li><a href='/docs/automation/trigger/'>Triggers </a></li>
<li><a href='/docs/automation/condition/'>Conditions </a></li>
<li><a href='/docs/automation/action/'>Actions </a></li>
<li><a href='/docs/automation/templating/'>Templates </a></li>
</ul>
</li>
<li>
<b><a href='/docs/frontend/'>Frontend </a></b>
<ul>
<li><a href='/docs/frontend/mobile/'>Android/iOS Homescreen </a></li>
<li><a href='/docs/frontend/webserver/'>Web server fingerprint </a></li>
<li><a href='/docs/frontend/browsers/'>Browser Compatibility List </a></li>
</ul>
</li>
<li>
<b><a href='/docs/backend/'>Backend </a></b>
<ul>
<li><a href='/docs/backend/database/'>Database </a></li>
<li><a href='/docs/backend/updater/'>Updater </a></li>
<li><a href='/developers/api/'>API </a></li>
</ul>
</li>
<li>
<b><a href='/docs/scripts/'>Scripts </a></b>
<ul>
<li><a href='/docs/scripts/service-calls/'>Service Calls </a></li>
<li><a href='/docs/scripts/conditions/'>Conditions </a></li>
<li><a href='/docs/scripts/editor/'>Editor </a></li>
</ul>
</li>
<li>
<b><a href='/docs/tools/'>Tools and Helpers </a></b>
<ul>
<li><a href='/docs/tools/dev-tools/'>Developer Tools </a></li>
<li><a href='/docs/tools/hass/'>hass </a></li>
<li><a href='/docs/tools/scripts/'>Scripts </a></li>
</ul>
</li>
<li>
<b><a href='/docs/z-wave/'>Z-Wave </a></b>
<ul>
<li><a href='/docs/z-wave/installation/'>Configuring the Z-Wave component </a></li>
<li><a href='/docs/z-wave/adding/'>Adding devices </a></li>
<li><a href='/docs/z-wave/control-panel/'>The Z-Wave control panel </a></li>
<li><a href='/docs/z-wave/controllers/'>Controllers </a></li>
<li><a href='/docs/z-wave/devices/'>Devices </a> and <a href='/docs/z-wave/entities/'>Entities </a></li>
<li><a href='/docs/z-wave/query-stage/'>Query Stages </a> for devices</li>
<li><a href='/docs/z-wave/device-specific/'>Device Specific </a> configuration</li>
<li><a href='/docs/z-wave/events/'>Events </a> and <a href='/docs/z-wave/services/'>Services </a></li>
</ul>
</li>
<li>
<b><a href='/docs/mqtt/'>MQTT </a></b>
<ul>
<li><a href='/docs/mqtt/broker/'>Broker </a></li>
<li><a href='/docs/mqtt/certificate/'>Certificate </a></li>
<li><a href='/docs/mqtt/discovery/'>Discovery </a></li>
<li><a href='/docs/mqtt/service/'>Publish service </a></li>
<li><a href='/docs/mqtt/birth_will/'>Birth and last will messages </a></li>
<li><a href='/docs/mqtt/testing/'>Testing your setup </a></li>
<li><a href='/docs/mqtt/logging/'>Logging </a></li>
<li><a href='/docs/mqtt/processing_json/'>Processing JSON </a></li>
</ul>
</li>
<li>
<b><a href='/docs/ecosystem/ios/'>iOS </a></b>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/basic/'>Basic notifications </a></li>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/sounds/'>Sounds </a></li>
<li><a href='/docs/ecosystem/ios/notifications/architecture/'>Architecture </a></li>
<li><a href='/docs/ecosystem/ios/notifications/privacy_security_rate_limits/'>Privacy, rate limiting and security </a></li>
</ul>
<li>Advanced notifications</li>
<ul>
<li><a href='/docs/ecosystem/ios/notifications/attachments/'>Attachments </a></li>
<li><a href='/docs/ecosystem/ios/notifications/content_extensions/'>Dynamic content </a></li>
<li><a href='/docs/ecosystem/ios/notifications/actions/'>Actionable notifications </a></li>
<li><a href='/docs/ecosystem/ios/notifications/requesting_location_updates/'>Requesting location updates </a></li>
</ul>
<li><a href='/docs/ecosystem/ios/location/'>Location Tracking </a></li>
<li><a href='/docs/ecosystem/ios/integration/'>Integration with other apps </a></li>
</ul>
</li>
<li>
<a href='/docs/ecosystem/'>Ecosystem </a>
<ul>
<li>
<a href='/docs/autostart/'>Autostart </a>
<ul>
<li><a href='/docs/autostart/systemd/'>systemd (Linux) </a></li>
<li><a href='/docs/autostart/upstart/'>Upstart (Linux) </a></li>
<li><a href='/docs/autostart/init.d/'>init.d (Linux) </a></li>
<li><a href='/docs/autostart/macos/'>macOS </a></li>
<li><a href='/docs/autostart/synology/'>Synology NAS </a></li>
</ul>
</li>
<li>
<a href='/docs/ecosystem/appdaemon/'>AppDaemon </a>
</li>
<li>
<a href='/docs/ecosystem/hadashboard/'>HADashboard </a>
</li>
<li>
<a href='/docs/ecosystem/notebooks/'>Notebooks </a>
<ul>
<li><a href='/docs/ecosystem/notebooks/'>Introduction </a></li>
<li><a href='/docs/ecosystem/notebooks/installation/'>Installation </a></li>
<li><a href='/docs/ecosystem/notebooks/graph/'>Graph </a></li>
<li><a href='/docs/ecosystem/notebooks/api/'>Home Assistant API </a></li>
<li><a href='/docs/ecosystem/notebooks/database/'>Database </a></li>
<li><a href='/docs/ecosystem/notebooks/stats/'>Statistics </a></li>
</ul>
</li>
<li>
Remote access
<ul>
<li><a href='/docs/ecosystem/apache/'>Apache </a></li>
<li><a href='/docs/ecosystem/caddy/'>Caddy Server </a></li>
<li><a href='/docs/ecosystem/nginx/'>NGINX </a></li>
<li><a href='/docs/ecosystem/nginx_subdomain/'>NGINX with subdomain</a></li>
<li><a href='/docs/ecosystem/tor/'>Tor Onion Service </a></li>
</ul>
</li>
<li>
<a href='/docs/ecosystem/certificates/'>Certificates </a>
<ul>
<li><a href='/docs/ecosystem/certificates/tls_self_signed_certificate/'>Self-signed certificate </a></li>
<li><a href='/docs/ecosystem/certificates/tls_domain_certificate/'>Certificate domain owners </a></li>
<li><a href='/docs/ecosystem/certificates/lets_encrypt/'>Let's Encrypt (detailed) </a></li>
</ul>
</li>
<li>
Backup
<ul>
<li><a href='/docs/ecosystem/backup/backup_github/'>Backup to GitHub </a></li>
<li><a href='/docs/ecosystem/backup/backup_dropbox/'>Backup to Dropbox </a></li>
<li><a href='/docs/ecosystem/backup/backup_usb/'>Backup to USB device </a></li>
</ul>
</li>
<li><a href='/docs/ecosystem/scenegen/'>scenegen </a></li>
<li><a href='/docs/ecosystem/synology/'>Synology </a></li>
<li><a href='/docs/ecosystem/hass-configurator/'>HASS Configurator </a></li>
</ul>
</ul>
</div>
</section>
</div>
</aside>
</div>
</div>
<footer>
<div class="grid-wrapper">
<div class="grid">
<div class="grid__item">
<div class="copyright">
<a rel="me" href='https://twitter.com/home_assistant'><i class="icon-twitter"></i></a>
<a rel="me" href='https://facebook.com/homeassistantio'><i class="icon-facebook"></i></a>
<a rel="me" href='https://plus.google.com/110560654828510104551'><i class="icon-google-plus"></i></a>
<a rel="me" href='https://github.com/home-assistant/home-assistant'><i class="icon-github"></i></a>
<div class="credit">
Contact us at <a href='mailto:hello@home-assistant.io'>hello@home-assistant.io</a> (no support!).<br>
Website powered by <a href='http://jekyllrb.com/'>Jekyll</a> and the <a href='https://github.com/coogie/oscailte'>Oscalite theme</a>.<br />
Hosted by <a href='https://pages.github.com/'>GitHub</a> and served by <a href='https://cloudflare.com'>CloudFlare</a>.
</div>
<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" /></a><br /><span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">home-assistant.io</span> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.
</div>
</div>
</div>
</div>
</footer>
<script>
var _gaq=[['_setAccount','UA-57927901-1'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.css" />
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/2/docsearch.min.js"></script>
<script type="text/javascript">
docsearch({
apiKey: 'ae96d94b201c5444c8a443093edf3efb',
indexName: 'home-assistant',
inputSelector: '#search',
debug: false // Set debug to true if you want to inspect the dropdown
});
document.querySelector('.search .close').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'none';
});
document.querySelector('.show-search').addEventListener('click', function(ev) {
ev.preventDefault();
document.querySelector('.search-container').style.display = 'block';
document.getElementById('toggle').checked = false;
document.querySelector('.search-container input').focus();
});
</script>
</body>
</html>