QT/superset2
1
0
Fork 0
mirror of https://github.com/apache/superset.git synced 2026-05-07 08:54:23 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
52ecb3e78706a9f99e9a182d64e2372ed478a731
superset2/installation.html
Maxime Beauchemin 52ecb3e787 Doc version as of 2016-06-11
2016-06-11 12:44:40 -07:00

397 lines
25 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Installation &amp; Configuration &mdash; caravel documentation</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/docs.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="top" title="caravel documentation" href="index.html" />
<link rel="next" title="Tutorial" href="tutorial.html" />
<link rel="prev" title="Overview" href="index.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
</head>
<body role="document">
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="index.html">
Caravel Documentation</a>
<span class="navbar-text navbar-version pull-left"><b></b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="index.html">Topics <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1 current"><a class="current reference internal" href="#">Installation &amp; Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
<li class="toctree-l1"><a class="reference internal" href="videos.html">Videos</a></li>
<li class="toctree-l1"><a class="reference internal" href="gallery.html">Gallery</a></li>
<li class="toctree-l1"><a class="reference internal" href="druid.html">Druid</a></li>
<li class="toctree-l1"><a class="reference internal" href="faq.html">FAQ</a></li>
</ul>
</ul>
</li>
<li class="dropdown">
<a role="button"
id="dLabelLocalToc"
data-toggle="dropdown"
data-target="#"
href="#">Page <b class="caret"></b></a>
<ul class="dropdown-menu localtoc"
role="menu"
aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Installation &amp; Configuration</a><ul>
<li><a class="reference internal" href="#getting-started">Getting Started</a></li>
<li><a class="reference internal" href="#os-dependencies">OS dependencies</a></li>
<li><a class="reference internal" href="#caravel-installation-and-initialization">Caravel installation and initialization</a></li>
<li><a class="reference internal" href="#configuration">Configuration</a></li>
<li><a class="reference internal" href="#database-dependencies">Database dependencies</a></li>
<li><a class="reference internal" href="#caching">Caching</a></li>
<li><a class="reference internal" href="#deeper-sqlalchemy-integration">Deeper SQLAlchemy integration</a></li>
<li><a class="reference internal" href="#schemas-postgres-redshift">Schemas (Postgres &amp; Redshift)</a></li>
<li><a class="reference internal" href="#ssl-access-to-databases">SSL Access to databases</a></li>
<li><a class="reference internal" href="#druid">Druid</a></li>
<li><a class="reference internal" href="#cors">CORS</a></li>
<li><a class="reference internal" href="#upgrading">Upgrading</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li class="hidden-sm"></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container mainbody">
<div class="section" id="installation-configuration">
<h1>Installation &amp; Configuration<a class="headerlink" href="#installation-configuration" title="Permalink to this headline"></a></h1>
<div class="section" id="getting-started">
<h2>Getting Started<a class="headerlink" href="#getting-started" title="Permalink to this headline"></a></h2>
<p>Caravel is currently only tested using Python 2.7.*. Python 3 support is
on the roadmap, Python 2.6 won&#8217;t be supported.</p>
</div>
<div class="section" id="os-dependencies">
<h2>OS dependencies<a class="headerlink" href="#os-dependencies" title="Permalink to this headline"></a></h2>
<p>Caravel stores database connection information in its metadata database.
For that purpose, we use the <code class="docutils literal"><span class="pre">cryptography</span></code> Python library to encrypt
connection passwords. Unfortunately this library has OS level dependencies.</p>
<p>You may want to attempt the next step
(&#8220;Caravel installation and initialization&#8221;) and come back to this step if
you encounter an error.</p>
<p>Here&#8217;s how to install them:</p>
<p>For <strong>Debian</strong> and <strong>Ubuntu</strong>, the following command will ensure that
the required dependencies are installed:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">build</span><span class="o">-</span><span class="n">essential</span> <span class="n">libssl</span><span class="o">-</span><span class="n">dev</span> <span class="n">libffi</span><span class="o">-</span><span class="n">dev</span> <span class="n">python</span><span class="o">-</span><span class="n">dev</span> <span class="n">python</span><span class="o">-</span><span class="n">pip</span>
</pre></div>
</div>
<p>For <strong>Fedora</strong> and <strong>RHEL-derivatives</strong>, the following command will ensure
that the required dependencies are installed:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">sudo</span> <span class="n">yum</span> <span class="n">upgrade</span> <span class="n">python</span><span class="o">-</span><span class="n">setuptools</span>
<span class="n">sudo</span> <span class="n">yum</span> <span class="n">install</span> <span class="n">gcc</span> <span class="n">libffi</span><span class="o">-</span><span class="n">devel</span> <span class="n">python</span><span class="o">-</span><span class="n">devel</span> <span class="n">python</span><span class="o">-</span><span class="n">pip</span> <span class="n">python</span><span class="o">-</span><span class="n">wheel</span> <span class="n">openssl</span><span class="o">-</span><span class="n">devel</span>
</pre></div>
</div>
<p><strong>OSX</strong>, system python is not recommended. brew&#8217;s python also ships with pip</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">brew</span> <span class="n">install</span> <span class="n">pkg</span><span class="o">-</span><span class="n">config</span> <span class="n">libffi</span> <span class="n">openssl</span> <span class="n">python</span>
<span class="n">env</span> <span class="n">LDFLAGS</span><span class="o">=</span><span class="s2">&quot;-L$(brew --prefix openssl)/lib&quot;</span> <span class="n">CFLAGS</span><span class="o">=</span><span class="s2">&quot;-I$(brew --prefix openssl)/include&quot;</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span>
</pre></div>
</div>
<p><strong>Windows</strong> isn&#8217;t officially supported at this point, but if you want to
attempt it, download <a class="reference external" href="https://bootstrap.pypa.io/get-pip.py">get-pip.py</a>, and run <code class="docutils literal"><span class="pre">python</span> <span class="pre">get-pip.py</span></code> which may need admin access. Then run the following:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">C</span><span class="p">:</span>\<span class="o">&gt;</span> \<span class="n">path</span>\<span class="n">to</span>\<span class="n">vcvarsall</span><span class="o">.</span><span class="n">bat</span> <span class="n">x86_amd64</span>
<span class="n">C</span><span class="p">:</span>\<span class="o">&gt;</span> <span class="nb">set</span> <span class="n">LIB</span><span class="o">=</span><span class="n">C</span><span class="p">:</span>\<span class="n">OpenSSL</span><span class="o">-</span><span class="mf">1.0</span><span class="o">.</span><span class="mi">1</span><span class="n">f</span><span class="o">-</span><span class="mi">64</span><span class="n">bit</span>\<span class="n">lib</span><span class="p">;</span><span class="o">%</span><span class="n">LIB</span><span class="o">%</span>
<span class="n">C</span><span class="p">:</span>\<span class="o">&gt;</span> <span class="nb">set</span> <span class="n">INCLUDE</span><span class="o">=</span><span class="n">C</span><span class="p">:</span>\<span class="n">OpenSSL</span><span class="o">-</span><span class="mf">1.0</span><span class="o">.</span><span class="mi">1</span><span class="n">f</span><span class="o">-</span><span class="mi">64</span><span class="n">bit</span>\<span class="n">include</span><span class="p">;</span><span class="o">%</span><span class="n">INCLUDE</span><span class="o">%</span>
<span class="n">C</span><span class="p">:</span>\<span class="o">&gt;</span> <span class="n">pip</span> <span class="n">install</span> <span class="n">cryptography</span>
<span class="c1"># You may also have to create C:\Temp</span>
<span class="n">C</span><span class="p">:</span>\<span class="o">&gt;</span> <span class="n">md</span> <span class="n">C</span><span class="p">:</span>\<span class="n">Temp</span>
</pre></div>
</div>
</div>
<div class="section" id="caravel-installation-and-initialization">
<h2>Caravel installation and initialization<a class="headerlink" href="#caravel-installation-and-initialization" title="Permalink to this headline"></a></h2>
<p>Follow these few simple steps to install Caravel.:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># Install caravel</span>
<span class="n">pip</span> <span class="n">install</span> <span class="n">caravel</span>
<span class="c1"># Create an admin user</span>
<span class="n">fabmanager</span> <span class="n">create</span><span class="o">-</span><span class="n">admin</span> <span class="o">--</span><span class="n">app</span> <span class="n">caravel</span>
<span class="c1"># Initialize the database</span>
<span class="n">caravel</span> <span class="n">db</span> <span class="n">upgrade</span>
<span class="c1"># Create default roles and permissions</span>
<span class="n">caravel</span> <span class="n">init</span>
<span class="c1"># Load some data to play with</span>
<span class="n">caravel</span> <span class="n">load_examples</span>
<span class="c1"># Start the development web server</span>
<span class="n">caravel</span> <span class="n">runserver</span> <span class="o">-</span><span class="n">d</span>
</pre></div>
</div>
<p>After installation, you should be able to point your browser to the right
hostname:port <a class="reference external" href="http://localhost:8088">http://localhost:8088</a>, login using
the credential you entered while creating the admin account, and navigate to
<cite>Menu -&gt; Admin -&gt; Refresh Metadata</cite>. This action should bring in all of
your datasources for Caravel to be aware of, and they should show up in
<cite>Menu -&gt; Datasources</cite>, from where you can start playing with your data!</p>
</div>
<div class="section" id="configuration">
<h2>Configuration<a class="headerlink" href="#configuration" title="Permalink to this headline"></a></h2>
<p>To configure your application, you need to create a file (module)
<code class="docutils literal"><span class="pre">caravel_config.py</span></code> and make sure it is in your PYTHONPATH. Here are some
of the parameters you can copy / paste in that configuration module:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1">#---------------------------------------------------------</span>
<span class="c1"># Caravel specific config</span>
<span class="c1">#---------------------------------------------------------</span>
<span class="n">ROW_LIMIT</span> <span class="o">=</span> <span class="mi">5000</span>
<span class="n">CARAVEL_WORKERS</span> <span class="o">=</span> <span class="mi">16</span>
<span class="n">CARAVEL_WEBSERVER_PORT</span> <span class="o">=</span> <span class="mi">8088</span>
<span class="c1">#---------------------------------------------------------</span>
<span class="c1">#---------------------------------------------------------</span>
<span class="c1"># Flask App Builder configuration</span>
<span class="c1">#---------------------------------------------------------</span>
<span class="c1"># Your App secret key</span>
<span class="n">SECRET_KEY</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="se">\2\1</span><span class="s1">thisismyscretkey</span><span class="se">\1\2</span><span class="s1">\e\y\y\h&#39;</span>
<span class="c1"># The SQLAlchemy connection string to your database backend</span>
<span class="c1"># This connection defines the path to the database that stores your</span>
<span class="c1"># caravel metadata (slices, connections, tables, dashboards, ...).</span>
<span class="c1"># Note that the connection information to connect to the datasources</span>
<span class="c1"># you want to explore are managed directly in the web UI</span>
<span class="n">SQLALCHEMY_DATABASE_URI</span> <span class="o">=</span> <span class="s1">&#39;sqlite:////tmp/caravel.db&#39;</span>
<span class="c1"># Flask-WTF flag for CSRF</span>
<span class="n">CSRF_ENABLED</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</div>
<p>This file also allows you to define configuration parameters used by
Flask App Builder, the web framework used by Caravel. Please consult
the <a class="reference external" href="http://flask-appbuilder.readthedocs.org/en/latest/config.html">Flask App Builder Documentation</a>
for more information on how to configure Caravel.</p>
</div>
<div class="section" id="database-dependencies">
<h2>Database dependencies<a class="headerlink" href="#database-dependencies" title="Permalink to this headline"></a></h2>
<p>Caravel does not ship bundled with connectivity to databases, except
for Sqlite, which is part of the Python standard library.
You&#8217;ll need to install the required packages for the database you
want to use as your metadata database as well as the packages needed to
connect to the databases you want to access through Caravel.</p>
<p>Here&#8217;s a list of some of the recommended packages.</p>
<table border="1" class="docutils">
<colgroup>
<col width="15%" />
<col width="37%" />
<col width="49%" />
</colgroup>
<thead valign="bottom">
<tr class="row-odd"><th class="head">database</th>
<th class="head">pypi package</th>
<th class="head">SQLAlchemy URI prefix</th>
</tr>
</thead>
<tbody valign="top">
<tr class="row-even"><td>MySQL</td>
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">mysqlclient</span></code></td>
<td><code class="docutils literal"><span class="pre">mysql://</span></code></td>
</tr>
<tr class="row-odd"><td>Postgres</td>
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">psycopg2</span></code></td>
<td><code class="docutils literal"><span class="pre">postgresql+psycopg2://</span></code></td>
</tr>
<tr class="row-even"><td>Presto</td>
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pyhive</span></code></td>
<td><code class="docutils literal"><span class="pre">presto://</span></code></td>
</tr>
<tr class="row-odd"><td>Oracle</td>
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">cx_Oracle</span></code></td>
<td><code class="docutils literal"><span class="pre">oracle://</span></code></td>
</tr>
<tr class="row-even"><td>sqlite</td>
<td>&nbsp;</td>
<td><code class="docutils literal"><span class="pre">sqlite://</span></code></td>
</tr>
<tr class="row-odd"><td>Redshift</td>
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">sqlalchemy-redshift</span></code></td>
<td><code class="docutils literal"><span class="pre">redshift+psycopg2://</span></code></td>
</tr>
<tr class="row-even"><td>MSSQL</td>
<td><code class="docutils literal"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">pymssql</span></code></td>
<td><code class="docutils literal"><span class="pre">mssql://</span></code></td>
</tr>
</tbody>
</table>
<p>Note that many other database are supported, the main criteria being the
existence of a functional SqlAlchemy dialect and Python driver. Googling
the keyword <code class="docutils literal"><span class="pre">sqlalchemy</span></code> in addition of a keyword that describes the
database you want to connect to should get you to the right place.</p>
</div>
<div class="section" id="caching">
<h2>Caching<a class="headerlink" href="#caching" title="Permalink to this headline"></a></h2>
<p>Caravel uses <a class="reference external" href="https://pythonhosted.org/Flask-Cache/">Flask-Cache</a> for
caching purpose. Configuring your caching backend is as easy as providing
a <code class="docutils literal"><span class="pre">CACHE_CONFIG</span></code>, constant in your <code class="docutils literal"><span class="pre">caravel_config.py</span></code> that
complies with the Flask-Cache specifications.</p>
<p>Flask-Cache supports multiple caching backends (Redis, Memcache,
SimpleCache (in-memory), or the local filesystem).</p>
<p>For setting your timeouts, this is done in the Caravel metadata and goes
up the &#8220;timeout searchpath&#8221;, from your slice configuration, to your
data source&#8217;s configuration, to your database&#8217;s and ultimately falls back
into your global default defined in <code class="docutils literal"><span class="pre">CACHE_CONFIG</span></code>.</p>
</div>
<div class="section" id="deeper-sqlalchemy-integration">
<h2>Deeper SQLAlchemy integration<a class="headerlink" href="#deeper-sqlalchemy-integration" title="Permalink to this headline"></a></h2>
<p>It is possible to tweak the database connection information using the
parameters exposed by SQLAlchemy. In the <code class="docutils literal"><span class="pre">Database</span></code> edit view, you will
find an <code class="docutils literal"><span class="pre">extra</span></code> field as a <code class="docutils literal"><span class="pre">JSON</span></code> blob.</p>
<a class="reference internal image-reference" href="_images/add_db.png"><img alt="_images/add_db.png" src="_images/add_db.png" style="width: 534.0px; height: 370.8px;" /></a>
<p>This JSON string contains extra configuration elements. The <code class="docutils literal"><span class="pre">engine_params</span></code>
object gets unpacked into the
<a class="reference external" href="http://docs.sqlalchemy.org/en/latest/core/engines.html#sqlalchemy.create_engine">sqlalchemy.create_engine</a> call,
while the <code class="docutils literal"><span class="pre">metadata_params</span></code> get unpacked into the
<a class="reference external" href="http://docs.sqlalchemy.org/en/rel_1_0/core/metadata.html#sqlalchemy.schema.MetaData">sqlalchemy.MetaData</a> call. Refer to the SQLAlchemy docs for more information.</p>
</div>
<div class="section" id="schemas-postgres-redshift">
<h2>Schemas (Postgres &amp; Redshift)<a class="headerlink" href="#schemas-postgres-redshift" title="Permalink to this headline"></a></h2>
<p>Postgres and Redshift, as well as other database,
use the concept of <strong>schema</strong> as a logical entity
on top of the <strong>database</strong>. For Caravel to connect to a specific schema,
there&#8217;s a <strong>schema</strong> parameter you can set in the table form.</p>
</div>
<div class="section" id="ssl-access-to-databases">
<h2>SSL Access to databases<a class="headerlink" href="#ssl-access-to-databases" title="Permalink to this headline"></a></h2>
<p>This example worked with a MySQL database that requires SSL. The configuration
may differ with other backends. This is what was put in the <code class="docutils literal"><span class="pre">extra</span></code>
parameter</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">&quot;metadata_params&quot;</span><span class="p">:</span> <span class="p">{},</span>
<span class="s2">&quot;engine_params&quot;</span><span class="p">:</span> <span class="p">{</span>
<span class="s2">&quot;connect_args&quot;</span><span class="p">:{</span>
<span class="s2">&quot;sslmode&quot;</span><span class="p">:</span><span class="s2">&quot;require&quot;</span><span class="p">,</span>
<span class="s2">&quot;sslrootcert&quot;</span><span class="p">:</span> <span class="s2">&quot;/path/to/my/pem&quot;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="druid">
<h2>Druid<a class="headerlink" href="#druid" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li>From the UI, enter the information about your clusters in the
<code class="docutils literal"><span class="pre">Admin-&gt;Clusters</span></code> menu by hitting the + sign.</li>
<li>Once the Druid cluster connection information is entered, hit the
<code class="docutils literal"><span class="pre">Admin-&gt;Refresh</span> <span class="pre">Metadata</span></code> menu item to populate</li>
<li>Navigate to your datasources</li>
</ul>
<p>Note that you can run the <code class="docutils literal"><span class="pre">caravel</span> <span class="pre">refresh_druid</span></code> command to refresh the
metadata from your Druid cluster(s)</p>
</div>
<div class="section" id="cors">
<h2>CORS<a class="headerlink" href="#cors" title="Permalink to this headline"></a></h2>
<p>The extra CORS Dependency must be installed:</p>
<blockquote>
<div>caravel[cors]</div></blockquote>
<p>The following keys in <cite>caravel_config.py</cite> can be specified to configure CORS:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">ENABLE_CORS</span></code>: Must be set to True in order to enable CORS</li>
<li><code class="docutils literal"><span class="pre">CORS_OPTIONS</span></code>: options passed to Flask-CORS (<cite>documentation &lt;http://flask-cors.corydolphin.com/en/latest/api.html#extension&gt;</cite>)</li>
</ul>
</div>
<div class="section" id="upgrading">
<h2>Upgrading<a class="headerlink" href="#upgrading" title="Permalink to this headline"></a></h2>
<p>Upgrading should be as straightforward as running:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">caravel</span> <span class="o">--</span><span class="n">upgrade</span>
<span class="n">caravel</span> <span class="n">db</span> <span class="n">upgrade</span>
</pre></div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.<br/>
</p>
</div>
</footer>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink