<commit_before>## Introduction

This Installation WireCloud version 0.9 (starting from FIWARE release 5.2). Any
feedback on this document is highly welcomed, including bugs, typos or things
you think should be included but are not. Please send it to the "Contact Person"
email that appears in the [Catalogue page for this GEi][catalogue].

[catalogue]: http://catalogue.fiware.org/enablers/application-mashup-wirecloud


## Requirements

This section describes all the requirements of a basic WireCloud installation. **However, these dependencies are not meant to be installed manually in this step, as they will be installed throughout the documentation:**

- A Database Manager (MySQL, PostgreSQL, SQLite3...)
- Python 2.7 or python 3.4+. In any case, the following python packages must be installed:
    - Django 1.5-1.9
    - South 1.0+
    - lxml 2.3.0+
    - django-appconf 1.0.1+
    - django-compressor 1.4-1.6 when using Django 1.5-1.7, django_compressor 2.0+ when using Django 1.8-1.9
    - rdflib 3.2.0+
    - requests 2.1.0+
    - futures 2.1.3+ (only on python 2.7)
    - selenium 2.41+
    - pytz
    - django_relatives
    - user-agents
    - regex
    - markdown
    - whoosh 2.5.6+
    - pycrypto
    - pyScss 1.3.4+
    - Pygments

All these dependencies are available for Linux, Mac OS and Windows, so WireCloud should work on any of these operating systems. However, it is better to use Debian Wheezy+, CentOS 7+, Ubuntu 12.04+ or Mac OS X 10.9 (only recommended for development/testing) as these operating systems are actively tested. Specifically, this installation guide was tested in the following systems:

- Ubuntu 14.04
- Ubuntu 12.04
- CentOS 7
- Debian Wheezy
- Debian Jessie
- Mac OS 10.9+

> **NOTE:** WireCloud can make use of the Marketplace, Store and Repository GEs. If you want to exploit this support, you can choose between installing these GEs or using any of the instances publicly available, for example, on FIWARE Lab (see the "Instances" tab of the corresponding entries at [http://catalogue.fiware.org](http://catalogue.fiware.org)).


## Installing basic dependencies

Before installing WireCloud, you will need to have some basic dependencies installed: python and [pip](http://www.pip-installer.org/en/latest/installing.html).

> **NOTE:** Although virtualenv is not required, you should install it before installing WireCloud if you intend to use it. It is highly recommended to use virtualenv (see the using [virtualenv section](#using-virtualenv) for more info) when installing WireCloud in CentOS/RedHat as those systems usually raise problems when installing python packages from their official repositories and, at the same time, from pip (a common case in those systems, as some packages should be updated for being compatible with WireCloud, but are requirements of other system applications). Anyway, although harder, it is possible to install WireCloud in those systems without using virtual environments.


### Debian/Ubuntu

This guide assumes you system's package list is up to date. Otherwise, run the following command:

	$ apt-get update

before installing software in Debian/Ubuntu:

    $ apt-get install python python-pip --no-install-recommends

It's also recommended to install the following packages:

    $ apt-get install python-dev libxml2-dev libxslt1-dev zlib1g-dev libpcre3-dev libcurl4-openssl-dev


### CentOS/RedHat

Python itself can be found in the official CentOS/RedHat repositories:

    $ yum install python

Whereas pip and other packages should be installed from 3rd party repositories. The most common one is the EPEL repository (see http://fedoraproject.org/wiki/EPEL for instructions about how to add it). If you has such a repository, you will be able to install pip using the following command:

    $ yum install python-pip


It's also recommended to install the following packages:

    $ yum install gcc python-devel libxslt-devel zlib-devel pcre-devel libcurl-devel


### Mac OS

Python comes installed by default in Mac OS, so you don't need to install it. pip can be installed using the following command:

    $ sudo easy_install pip

However, we recommend you to upgrade your python installation using the [Homebrew](http://brew.sh/) tools for Mac:

    $ brew install python

This command will install, as bonus, the pip command tool.

It's also recommended to install the following package:

    $ brew install pcre

You will also need the command line developer tools for xcode. You can install them by running the following command:

    $ xcode-select --install

### Using virtualenv

[virtualenv](http://virtualenv.readthedocs.org/en/latest/virtualenv.html) is a tool to create isolated Python environments. Those Virtual Environments, are an isolated working copy of Python which allows you to work on a specific project without worry of affecting other projects.

virtualenv can be installed using pip:

    $ pip install virtualenv

Once installed virtualenv, you will be able to create virtual environments using the following command:

    $ virtualenv venv

This will create an `venv` folder for storing all the resources related to the virtual environment. To begin using the virtual environment, it needs to be activated:

    $ source venv/bin/activate

You can then begin installing any new modules without affecting the system default Python or other virtual environments. If you are done working in the virtual environment for the moment, you can deactivate it:

    $ deactivate

This puts you back to the system’s default Python interpreter with all its installed libraries.

To delete a virtual environment, just delete its folder.


## Installing WireCloud using pip (recommended)

You can always install the latest stable version of WireCloud using pip:

    $ sudo pip install wirecloud

> **NOTE**: python distribution tools doesn't support conditional dependencies.
> We cannot force the use of `django_compressor` < 2.0 when installing `Django`
> 1.5-1.6 and `django_compressor` >= 2.0 when using `Django` 1.8-1.9, you must
> manually ensure the correct version of `django_compressor` is installed in
> your environment.


## Installing WireCloud from sources

The WireCloud source code is available on the [GitHub WireCloud repository](https://github.com/Wirecloud/wirecloud).

To get the latest development version of the code, you can choose between two options:

- Go to the WireCloud repository on GitHub, switch to the `0.9.x` branch (or select a specific 0.9.x tag, e.g. `0.9.0`) and click on the *Download ZIP* button to download the repository as a zip file, or just click on this [link](https://github.com/Wirecloud/wirecloud/zipball/0.9.x). Unzip it.
- Or use a [GIT](http://git-scm.com/) client to get the latest development version via Git:

        $ git clone git://github.com/Wirecloud/wirecloud.git
        $ cd wirecloud
        $ git checkout 0.9.x

> **NOTE:** The `0.9.x` branch provides the latests development for the `0.9`
> version of WireCloud (that is, the version described in this guide). The
> latest version of WireCloud is available in the `develop` branch. It's
> recommended to check if you are reading the latest version of this guide (e.g.
> following this [link][latest_docs]) if you are going to install the
> latest version of WireCloud from the `develop` branch instead of using the
> `0.9.x` branch.

Once downloaded the source code, you can install WireCloud using the `setup.py` script (this step requires root privileges):

    $ cd ${path_to_source_code}/src
    $ python setup.py bdist_wheel
    $ sudo pip install dist/wirecloud-${version}-py2.py3-none-any.whl

Where `${version}` is the version of WireCloud to install.

[latest_docs]: https://wirecloud.readthedocs.org/en/latest/installation_guide/


## Installing WireCloud using Docker

WireCloud can also be deployed using [Docker](https://www.docker.com/), the images can be found on [docker hub](https://hub.docker.com/r/fiware/wirecloud/). This guide doesn't cover WireCloud installation using docker, please refere to the [docker's documentation](https://docs.docker.com/userguide/dockerimages/), as it can be used as any other docker image (e.g. it can also be used with docker-machine); and to the documentation available on docker hub about the WireCloud's image for more info about how to procede in this case. Anyway, once installed, you can make changes in the configuration of your WireCloud container following the steps described in this guide as well as make use of any of the administration procedures described in the [Administration Guide](administration_guide.md) section.

> WireCloud's DockerFiles and image documentation are hosted on the [docker-wirecloud](https://github.com/Wirecloud/docker-wirecloud/) repository.

## Creating a new instance of WireCloud

Once installed WireCloud, you will have access to the `wirecloud-admin` script. This script is, among other things, used for deploy new instances of WireCloud. Before creating the instance, we recommend you to create a special user for managing and running WireCloud. For example, in Debian/Ubuntu:

    $ adduser --system --group --shell /bin/bash wirecloud

Then, create a new instance directory using the `startproject` command. This will create a new directory containing the `manage.py` script, the configuration files, ... related to the new instance. Moreover, you can add new python modules into this directory to customise your instance.

    $ cd /opt
    $ wirecloud-admin startproject wirecloud_instance

After creating the new instance, you have to configure it choosing a database, populating it and performing final DJango configurations. These steps can be skipped using the `--quick-start` option. This will configure the instance to use SQLite3 with a default admin user (password:<PASSWORD>). This method is very useful for creating a WireCloud instance for testing:

    $ cd /opt
    $ wirecloud-admin startproject wirecloud_instance --quick-start

If you make use of the `--quick-start` option, you should be able to go directly to the [Running WireCloud](#running-wirecloud) section.


## Database installation and configuration

To set up the database engine, it is necessary to modify the `DATABASE` configuration setting in the instance `settings.py` file (e.g. `/opt/wirecloud_instance/wirecloud_instance/settings.py`). You can use any of the [database engines supported by Django](https://docs.djangoproject.com/en/1.4/ref/settings/#databases).

The following examples show you how to configure SQLite and PostgreSQL databases.


### SQLite

Setting up a SQLite database can be just accomplished within seconds by using the following parameters into the `settings.py` file:

```python
DATABASES = {
      'default': {
             'ENGINE': 'django.db.backends.sqlite3',
             'NAME': '${dbfile}',
             'USER': '',
             'PASSWORD': '',
             'HOST': '',
             'PORT': '',
     }
}
```

where `${dbfile}` is the full path to the database file.

Python directly comes with support for SQLite, but we recommend you to install the pysqlite2 module as it provides a more updated driver:

    $ sudo pip install pysqlite

Finally, please take into account that SQLite database is **not recommended for production purposes**. It is only useful for evaluation purposes.


### PostgreSQL

For production purposes, PostgreSQL database is a much better choice. To do so, the following parameters must be set in `settings.py`:

```python
DATABASES = {
      'default': {
             'ENGINE': 'django.db.backends.postgresql_psycopg2',
             'NAME': '${dbname}',
             'USER': '${dbuser}',
             'PASSWORD': '${dbpassword}',
             'HOST': '${dbhost}',
             'PORT': '${dbport}',
     }
}
```

where `${dbname}` represents the name of the database, `${dbuser}` is the name of the user with privileges on the database and `${dbpassword}` is the password to use for authenticating the user. `${dbhost}` and `${dbport}` are the host and the port of the database server to use (leave these settings empty if the server is running on the same machine as WireCloud).

The only thing that remains is installing the python bindings for PostgreSQL:

    $ sudo pip install psycopg2

Or alternatively, for Debian/Ubuntu:

    $ sudo apt-get install python-psycopg2

#### Installing PostgresSQL on Debian/Ubuntu

First install the object-relational database system.

    $ sudo apt-get install postgresql

Afterwards you have to create the project Database. We assume that your user has super administrator permissions in PostgreSQL. This usually means that you have to login as the postgres user (i.e. `$ sudo su postgres`).

Both the PostgreSQL database and its user can be created with the following commands:

    $ createuser ${dbuser} [-P]
    $ createdb --owner=${dbuser} ${dbname}

If you want to create a password protected user you must use the `-P` option.

If you want to create a database called 'wirecloud' and a user called 'wc_user' with privileges on this database, you should write the following:

    $ createuser wc_user [-P]
    $ createdb --owner=wc_user wirecloud

Finally, it is also needed to allow local connections to the database, i.e. from the computer you are installing WireCloud. To do so, add the following rules to the beginning of the `/etc/postgresql/X.X/main/pg_hba.conf` file. In other words, the following two rules MUST be the first two rules of the file:

    # TYPE  DATABASE           USER            CIDR-ADDRESS          METHOD
    local   wirecloud          wc_user                               trust
    local   test_wirecloud     wc_user                               trust # only necessary for testing Wirecloud

Reload `pg_hba.conf` in PostgreSQL server with the following command:

    $ sudo service postgresql reload

And finally, restart PostgreSQL and check if your user has access using this command:

    $ psql wirecloud -U wc_user

#### Installing PostgresSQL on other platforms

Please, follow the [oficial PostgresSQL installation guide](http://www.postgresql.org/download/).

## Database population

Before running WireCloud, it is necessary to populate the database. This can be
achieved by using this command:

    $ python manage.py migrate

> **NOTE**: use the following command if you are using Django 1.5-1.6:
>
>       $ python manage.py syncdb --migrate

This command creates some tables and asks you if you want to create a Django
superuser. This user is required to login into WireCloud and to be able to
perform administrative tasks; please respond yes. An example of the command
output, where `user`/`password` are `<PASSWORD>`, is the following:

    ...

    You just installed Django's auth system, which means you don't have any superusers defined.
    Would you like to create one now? (yes/no): yes
    Username (leave blank to use 'wirecloud'): admin
    E-mail address: <EMAIL>
    Password: ***** (admin)
    Password (again): ***** (admin)

## Extra options

Here’s a list of general settings available in WireCloud and their default values. These settings are configured in the `settings.py` file. Also, take into account that most of these settings are based on settings provided by Django (see [Django documentation](https://docs.djangoproject.com/en/dev/ref/settings) for more info).


### ADMINS
> (Tuple, default: `()` [Empty tuple])

A tuple that lists people who get code error notifications. When `DEBUG=False` and a view raises an exception, WireCloud will email these people with the full exception information. Each member of the tuple should be a tuple of (Full name, email address). Example:

```python
(('John', '<EMAIL>'), ('Mary', '<EMAIL>'))
```

Note that Django will email all of these people whenever an error happens.


### ALLOW_ANONYMOUS_USER
> (Boolean; default: `True`)

A boolean that turns on/off anonymous user access. Take into account that disabling anonymous access will reduce the usefulness of embedded and public workspaces as they will require users to be logged in.


### DEBUG
> (Boolean; default: `False`)

A boolean that turns on/off debug mode.

**Never deploy a site into production with `DEBUG` turned on.**

One of the main features of debug mode is the display of detailed error pages. If WireCloud raises an exception when `DEBUG` is `True`, Django will display a detailed traceback, including a lot of metadata about your environment, such as all the currently defined Django settings (from `settings.py`).


### DEFAULT_LANGUAGE
> (String; default: "browser")

Language code to use by default (e.g. "en"). This setting also support other values: "browser", meaning "use the language detected from browser" and "default" for using the value of the `LANGUAGE_CODE` setting.


### FORCE_DOMAIN
> (String, default: `None`)

Set `FORCE_DOMAIN` using an string if you want to force WireCloud to use a
concrete domain name (without including the port) when building internal URLs.
If this setting is `None` (the default), WireCloud will try to use the [Django's
sites framework](https://docs.djangoproject.com/en/1.4/ref/contrib/sites/) for
obtaining the domain info. If the sites framework is not used, the domain is
extracted from the request.

> This setting is mainly useful when WireCloud is behind a web server acting as
> proxy.


### FORCE_PORT
> (Integer, default: `None`)

Set `FORCE_PORT` using a number if you want to force WireCloud to use
that port when building internal URLs.

If this setting is `None` (the default), WireCloud will use the port info from
incoming requests for building internal URLs.

> This setting is mainly useful when WireCloud is behind a web server acting as
> proxy.


### FORCE_PROTO
> (String, default: `None`)

Set `FORCE_PROTO` to "http" or to "https" if you want to force WireCloud to use
one of those schemes when building internal URLs.

If this setting is `None` (the default), WireCloud will check if the request
comes from a secure connection and, in that case, it will use https as the
scheme for building the internal URLs. In any other case, WireCloud will use
http as the scheme for the internal URLs.

> This setting is mainly useful when WireCloud is behind a web server acting as
> proxy.


### LANGUAGE_CODE
> (String; default: "en-us")

A string representing the language code to use as fallback when no translation exist for a given literal to the user’s preferred language. For example, U.S. English is "en-us".


### SERVER_EMAIL
> (String; default: 'root@localhost')

The email address that error messages come from, such as those sent to `ADMINS`.


### THEME_ACTIVE
> (String, default: "wirecloud.defaulttheme")

A string representing the module that will be use for theming WireCloud. Current
themes shipped with WireCloud are `wirecloud.defaulttheme`,
`wirecloud.fiwaretheme` and `wirecloud.fiwarelabtheme`. You can also use [custom
themes](development/platform/themes).

> **NOTE**: `wirecloud.fiwarelabtheme` was previously (WireCloud 0.8.1-) known as
> `wirecloud.oiltheme`. Although you can still reference it as
> `wirecloud.oiltheme` is recommended to switch to the new name:
> `wirecloud.fiwarelabtheme`.


### URL_MIDDLEWARE_CLASSES
> (Dictionary; default: A middleware configuration dictionary)

A data structure containing the middleware configuration per URL group where the URL group name are the keys of the dictionary and the value should be a tuple of middleware classes to use for that group.

You should use this setting as replacement of the Django's MIDDLEWARE_CLASSES setting (See [Django's middleware documentation](https://docs.djangoproject.com/en/dev/topics/http/middleware/))

Currently available groups are "default", "api" and "proxy". For example, if you want to add a middleware class to the "api" group, you can use the following code:

```python
URL_MIDDLEWARE_CLASSES['api'] += ('my.middleware.module.MyMiddlware',)
```


### WIRECLOUD_HTTPS_VERIFY
> *new in WireCloud 0.7.0*
>
> (Boolean or String, default: `True`)

Set `WIRECLOUD_HTTPS_VERIFY` to `False` if you want WireCloud not validate HTTPS
certificates. If this setting is `True` (the default), WireCloud will verify
https certificates using the CA certificates bundled with python requests or
using the certificates provided by the system (this depends on the procedure
followed for installing the python requests module). You can also provide a path
to a CA bundle file to use instead (e.g.
`WIRECLOUD_HTTPS_VERIFY = "/etc/ssl/certs/ca-certificates.crt"`).


## Django configuration

The `settings.py` file allows you to set several options in WireCloud. If
`DEBUG` is `False` you will need to collect WireCloud static files using the
following command and answering 'yes' when asked:

    $ python manage.py collectstatic

In addition, you should serve the static files with a fast performance http
server like [Apache](http://httpd.apache.org/), [Nginx](http://nginx.org/),
[Gunicorn](http://gunicorn.org/), etc. We provide documentation on
[how to serve WireCloud using Apache 2](#running-wirecloud-using-apache-2).
Anyway, if you want to use any of the other http servers (e.g using Gunicorn),
Django provides
[documentation on how to do it](https://docs.djangoproject.com/en/dev/howto/deployment/).

Finally, you can compress CSS and JavaScript code files for better performance
using the following command:

    $ python manage.py compress --force

> **NOTE:** Don't forget to rerun the collectstatic and compress commands each
> time the WireCloud code is updated, this include each time a WireCloud plugin
> or Django app is enabled/disabled and when the default theme is changed.


## Advanced configurations

### Installing the WireCloud Pub Sub add-on

The development of the Pub Sub add-on is carried out at they own [github
repository](https://github.com/conwetlab/wirecloud-pubsub). You can always find
the latest information about how to install and use it on the main page of the
repository.<commit_msg>Add documentation about the required versions of setuptools and wheel packages. See #120<commit_after>## Introduction

This Installation WireCloud version 0.9 (starting from FIWARE release 5.2). Any
feedback on this document is highly welcomed, including bugs, typos or things
you think should be included but are not. Please send it to the "Contact Person"
email that appears in the [Catalogue page for this GEi][catalogue].

[catalogue]: http://catalogue.fiware.org/enablers/application-mashup-wirecloud


## Requirements

This section describes all the requirements of a basic WireCloud installation. **However, these dependencies are not meant to be installed manually in this step, as they will be installed throughout the documentation:**

- A Database Manager (MySQL, PostgreSQL, SQLite3...)
- Python 2.7 or python 3.4+. In any case, the following python packages must be installed:
    - Django 1.5-1.9
    - South 1.0+
    - lxml 2.3.0+
    - django-appconf 1.0.1+
    - django-compressor 1.4-1.6 when using Django 1.5-1.7, django_compressor 2.0+ when using Django 1.8-1.9
    - rdflib 3.2.0+
    - requests 2.1.0+
    - futures 2.1.3+ (only on python 2.7)
    - selenium 2.41+
    - pytz
    - django_relatives
    - user-agents
    - regex
    - markdown
    - whoosh 2.5.6+
    - pycrypto
    - pyScss 1.3.4+
    - Pygments

All these dependencies are available for Linux, Mac OS and Windows, so WireCloud should work on any of these operating systems. However, it is better to use Debian Wheezy+, CentOS 7+, Ubuntu 12.04+ or Mac OS X 10.9 (only recommended for development/testing) as these operating systems are actively tested. Specifically, this installation guide was tested in the following systems:

- Ubuntu 14.04
- Ubuntu 12.04
- CentOS 7
- Debian Wheezy
- Debian Jessie
- Mac OS 10.9+

> **NOTE**: WireCloud can make use of the Marketplace, Store and Repository GEs. If you want to exploit this support, you can choose between installing these GEs or using any of the instances publicly available, for example, on FIWARE Lab (see the "Instances" tab of the corresponding entries at [http://catalogue.fiware.org](http://catalogue.fiware.org)).


## Installing basic dependencies

Before installing WireCloud, you will need to have some basic dependencies installed: python and [pip](http://www.pip-installer.org/en/latest/installing.html).

> **NOTE**: Although virtualenv is not required, you should install it before installing WireCloud if you intend to use it. It is highly recommended to use virtualenv (see the using [virtualenv section](#using-virtualenv) for more info) when installing WireCloud in CentOS/RedHat as those systems usually raise problems when installing python packages from their official repositories and, at the same time, from pip (a common case in those systems, as some packages should be updated for being compatible with WireCloud, but are requirements of other system applications). Anyway, although harder, it is possible to install WireCloud in those systems without using virtual environments.


### Debian/Ubuntu

This guide assumes you system's package list is up to date. Otherwise, run the following command:

	$ apt-get update

before installing software in Debian/Ubuntu:

    $ apt-get install python python-pip --no-install-recommends

It's also recommended to install the following packages:

    $ apt-get install python-dev libxml2-dev libxslt1-dev zlib1g-dev libpcre3-dev libcurl4-openssl-dev


### CentOS/RedHat

Python itself can be found in the official CentOS/RedHat repositories:

    $ yum install python

Whereas pip and other packages should be installed from 3rd party repositories. The most common one is the EPEL repository (see http://fedoraproject.org/wiki/EPEL for instructions about how to add it). If you has such a repository, you will be able to install pip using the following command:

    $ yum install python-pip


It's also recommended to install the following packages:

    $ yum install gcc python-devel libxslt-devel zlib-devel pcre-devel libcurl-devel


### Mac OS

Python comes installed by default in Mac OS, so you don't need to install it. pip can be installed using the following command:

    $ sudo easy_install pip

However, we recommend you to upgrade your python installation using the [Homebrew](http://brew.sh/) tools for Mac:

    $ brew install python

This command will install, as bonus, the pip command tool.

It's also recommended to install the following package:

    $ brew install pcre

You will also need the command line developer tools for xcode. You can install them by running the following command:

    $ xcode-select --install

### Using virtualenv

[virtualenv](http://virtualenv.readthedocs.org/en/latest/virtualenv.html) is a tool to create isolated Python environments. Those Virtual Environments, are an isolated working copy of Python which allows you to work on a specific project without worry of affecting other projects.

virtualenv can be installed using pip:

    $ pip install virtualenv

Once installed virtualenv, you will be able to create virtual environments using the following command:

    $ virtualenv venv

This will create an `venv` folder for storing all the resources related to the virtual environment. To begin using the virtual environment, it needs to be activated:

    $ source venv/bin/activate

You can then begin installing any new modules without affecting the system default Python or other virtual environments. If you are done working in the virtual environment for the moment, you can deactivate it:

    $ deactivate

This puts you back to the system’s default Python interpreter with all its installed libraries.

To delete a virtual environment, just delete its folder.


## Installing WireCloud using pip (recommended)

You can always install the latest stable version of WireCloud using pip:

    $ sudo pip install wirecloud

> **NOTE**: python distribution tools doesn't support conditional dependencies.
> We cannot force the use of `django_compressor` < 2.0 when installing `Django`
> 1.5-1.6 and `django_compressor` >= 2.0 when using `Django` 1.8-1.9, you must
> manually ensure the correct version of `django_compressor` is installed in
> your environment.


## Installing WireCloud from sources

The WireCloud source code is available on the [GitHub WireCloud repository](https://github.com/Wirecloud/wirecloud).

To get the latest development version of the code, you can choose between two options:

- Go to the WireCloud repository on GitHub, switch to the `0.9.x` branch (or select a specific 0.9.x tag, e.g. `0.9.0`) and click on the *Download ZIP* button to download the repository as a zip file, or just click on this [link](https://github.com/Wirecloud/wirecloud/zipball/0.9.x). Unzip it.
- Or use a [GIT](http://git-scm.com/) client to get the latest development version via Git:

        $ git clone git://github.com/Wirecloud/wirecloud.git
        $ cd wirecloud
        $ git checkout 0.9.x

> **NOTE**: The `0.9.x` branch provides the latests development for the `0.9`
> version of WireCloud (that is, the version described in this guide). The
> latest version of WireCloud is available in the `develop` branch. It's
> recommended to check if you are reading the latest version of this guide (e.g.
> following this [link][latest_docs]) if you are going to install the
> latest version of WireCloud from the `develop` branch instead of using the
> `0.9.x` branch.

Once downloaded the source code, you can install WireCloud using the `setup.py` script (this step requires root privileges):

    $ cd ${path_to_source_code}/src
    $ python setup.py bdist_wheel
    $ sudo pip install dist/wirecloud-${version}-py2.py3-none-any.whl

Where `${version}` is the version of WireCloud to install.

> **NOTE**: There are extra dependencies for being able to use the `setup.py`
> script: `setuptools` >= 18.5 and `wheel` > 0.24. You can install them using
> pip: `pip install "setuptools>18.5" "wheel>=0.24"`

[latest_docs]: https://wirecloud.readthedocs.org/en/latest/installation_guide/


## Installing WireCloud using Docker

WireCloud can also be deployed using [Docker](https://www.docker.com/), the images can be found on [docker hub](https://hub.docker.com/r/fiware/wirecloud/). This guide doesn't cover WireCloud installation using docker, please refere to the [docker's documentation](https://docs.docker.com/userguide/dockerimages/), as it can be used as any other docker image (e.g. it can also be used with docker-machine); and to the documentation available on docker hub about the WireCloud's image for more info about how to procede in this case. Anyway, once installed, you can make changes in the configuration of your WireCloud container following the steps described in this guide as well as make use of any of the administration procedures described in the [Administration Guide](administration_guide.md) section.

> WireCloud's DockerFiles and image documentation are hosted on the [docker-wirecloud](https://github.com/Wirecloud/docker-wirecloud/) repository.

## Creating a new instance of WireCloud

Once installed WireCloud, you will have access to the `wirecloud-admin` script. This script is, among other things, used for deploy new instances of WireCloud. Before creating the instance, we recommend you to create a special user for managing and running WireCloud. For example, in Debian/Ubuntu:

    $ adduser --system --group --shell /bin/bash wirecloud

Then, create a new instance directory using the `startproject` command. This will create a new directory containing the `manage.py` script, the configuration files, ... related to the new instance. Moreover, you can add new python modules into this directory to customise your instance.

    $ cd /opt
    $ wirecloud-admin startproject wirecloud_instance

After creating the new instance, you have to configure it choosing a database, populating it and performing final DJango configurations. These steps can be skipped using the `--quick-start` option. This will configure the instance to use SQLite3 with a default admin user (password:<PASSWORD>). This method is very useful for creating a WireCloud instance for testing:

    $ cd /opt
    $ wirecloud-admin startproject wirecloud_instance --quick-start

If you make use of the `--quick-start` option, you should be able to go directly to the [Running WireCloud](#running-wirecloud) section.


## Database installation and configuration

To set up the database engine, it is necessary to modify the `DATABASE` configuration setting in the instance `settings.py` file (e.g. `/opt/wirecloud_instance/wirecloud_instance/settings.py`). You can use any of the [database engines supported by Django](https://docs.djangoproject.com/en/1.4/ref/settings/#databases).

The following examples show you how to configure SQLite and PostgreSQL databases.


### SQLite

Setting up a SQLite database can be just accomplished within seconds by using the following parameters into the `settings.py` file:

```python
DATABASES = {
      'default': {
             'ENGINE': 'django.db.backends.sqlite3',
             'NAME': '${dbfile}',
             'USER': '',
             'PASSWORD': '',
             'HOST': '',
             'PORT': '',
     }
}
```

where `${dbfile}` is the full path to the database file.

Python directly comes with support for SQLite, but we recommend you to install the pysqlite2 module as it provides a more updated driver:

    $ sudo pip install pysqlite

Finally, please take into account that SQLite database is **not recommended for production purposes**. It is only useful for evaluation purposes.


### PostgreSQL

For production purposes, PostgreSQL database is a much better choice. To do so, the following parameters must be set in `settings.py`:

```python
DATABASES = {
      'default': {
             'ENGINE': 'django.db.backends.postgresql_psycopg2',
             'NAME': '${dbname}',
             'USER': '${dbuser}',
             'PASSWORD': '${<PASSWORD>}',
             'HOST': '${dbhost}',
             'PORT': '${dbport}',
     }
}
```

where `${dbname}` represents the name of the database, `${dbuser}` is the name of the user with privileges on the database and `${dbpassword}` is the password to use for authenticating the user. `${dbhost}` and `${dbport}` are the host and the port of the database server to use (leave these settings empty if the server is running on the same machine as WireCloud).

The only thing that remains is installing the python bindings for PostgreSQL:

    $ sudo pip install psycopg2

Or alternatively, for Debian/Ubuntu:

    $ sudo apt-get install python-psycopg2

#### Installing PostgresSQL on Debian/Ubuntu

First install the object-relational database system.

    $ sudo apt-get install postgresql

Afterwards you have to create the project Database. We assume that your user has super administrator permissions in PostgreSQL. This usually means that you have to login as the postgres user (i.e. `$ sudo su postgres`).

Both the PostgreSQL database and its user can be created with the following commands:

    $ createuser ${dbuser} [-P]
    $ createdb --owner=${dbuser} ${dbname}

If you want to create a password protected user you must use the `-P` option.

If you want to create a database called 'wirecloud' and a user called 'wc_user' with privileges on this database, you should write the following:

    $ createuser wc_user [-P]
    $ createdb --owner=wc_user wirecloud

Finally, it is also needed to allow local connections to the database, i.e. from the computer you are installing WireCloud. To do so, add the following rules to the beginning of the `/etc/postgresql/X.X/main/pg_hba.conf` file. In other words, the following two rules MUST be the first two rules of the file:

    # TYPE  DATABASE           USER            CIDR-ADDRESS          METHOD
    local   wirecloud          wc_user                               trust
    local   test_wirecloud     wc_user                               trust # only necessary for testing Wirecloud

Reload `pg_hba.conf` in PostgreSQL server with the following command:

    $ sudo service postgresql reload

And finally, restart PostgreSQL and check if your user has access using this command:

    $ psql wirecloud -U wc_user

#### Installing PostgresSQL on other platforms

Please, follow the [oficial PostgresSQL installation guide](http://www.postgresql.org/download/).

## Database population

Before running WireCloud, it is necessary to populate the database. This can be
achieved by using this command:

    $ python manage.py migrate

> **NOTE**: use the following command if you are using Django 1.5-1.6:
>
>       $ python manage.py syncdb --migrate

This command creates some tables and asks you if you want to create a Django
superuser. This user is required to login into WireCloud and to be able to
perform administrative tasks; please respond yes. An example of the command
output, where `user`/`password` are `admin`/`admin`, is the following:

    ...

    You just installed Django's auth system, which means you don't have any superusers defined.
    Would you like to create one now? (yes/no): yes
    Username (leave blank to use 'wirecloud'): admin
    E-mail address: <EMAIL>
    Password: ***** (admin)
    Password (again): ***** (admin)

## Extra options

Here’s a list of general settings available in WireCloud and their default values. These settings are configured in the `settings.py` file. Also, take into account that most of these settings are based on settings provided by Django (see [Django documentation](https://docs.djangoproject.com/en/dev/ref/settings) for more info).


### ADMINS
> (Tuple, default: `()` [Empty tuple])

A tuple that lists people who get code error notifications. When `DEBUG=False` and a view raises an exception, WireCloud will email these people with the full exception information. Each member of the tuple should be a tuple of (Full name, email address). Example:

```python
(('John', '<EMAIL>'), ('Mary', '<EMAIL>'))
```

Note that Django will email all of these people whenever an error happens.


### ALLOW_ANONYMOUS_USER
> (Boolean; default: `True`)

A boolean that turns on/off anonymous user access. Take into account that disabling anonymous access will reduce the usefulness of embedded and public workspaces as they will require users to be logged in.


### DEBUG
> (Boolean; default: `False`)

A boolean that turns on/off debug mode.

**Never deploy a site into production with `DEBUG` turned on.**

One of the main features of debug mode is the display of detailed error pages. If WireCloud raises an exception when `DEBUG` is `True`, Django will display a detailed traceback, including a lot of metadata about your environment, such as all the currently defined Django settings (from `settings.py`).


### DEFAULT_LANGUAGE
> (String; default: "browser")

Language code to use by default (e.g. "en"). This setting also support other values: "browser", meaning "use the language detected from browser" and "default" for using the value of the `LANGUAGE_CODE` setting.


### FORCE_DOMAIN
> (String, default: `None`)

Set `FORCE_DOMAIN` using an string if you want to force WireCloud to use a
concrete domain name (without including the port) when building internal URLs.
If this setting is `None` (the default), WireCloud will try to use the [Django's
sites framework](https://docs.djangoproject.com/en/1.4/ref/contrib/sites/) for
obtaining the domain info. If the sites framework is not used, the domain is
extracted from the request.

> This setting is mainly useful when WireCloud is behind a web server acting as
> proxy.


### FORCE_PORT
> (Integer, default: `None`)

Set `FORCE_PORT` using a number if you want to force WireCloud to use
that port when building internal URLs.

If this setting is `None` (the default), WireCloud will use the port info from
incoming requests for building internal URLs.

> This setting is mainly useful when WireCloud is behind a web server acting as
> proxy.


### FORCE_PROTO
> (String, default: `None`)

Set `FORCE_PROTO` to "http" or to "https" if you want to force WireCloud to use
one of those schemes when building internal URLs.

If this setting is `None` (the default), WireCloud will check if the request
comes from a secure connection and, in that case, it will use https as the
scheme for building the internal URLs. In any other case, WireCloud will use
http as the scheme for the internal URLs.

> This setting is mainly useful when WireCloud is behind a web server acting as
> proxy.


### LANGUAGE_CODE
> (String; default: "en-us")

A string representing the language code to use as fallback when no translation exist for a given literal to the user’s preferred language. For example, U.S. English is "en-us".


### SERVER_EMAIL
> (String; default: 'root@localhost')

The email address that error messages come from, such as those sent to `ADMINS`.


### THEME_ACTIVE
> (String, default: "wirecloud.defaulttheme")

A string representing the module that will be use for theming WireCloud. Current
themes shipped with WireCloud are `wirecloud.defaulttheme`,
`wirecloud.fiwaretheme` and `wirecloud.fiwarelabtheme`. You can also use [custom
themes](development/platform/themes).

> **NOTE**: `wirecloud.fiwarelabtheme` was previously (WireCloud 0.8.1-) known as
> `wirecloud.oiltheme`. Although you can still reference it as
> `wirecloud.oiltheme` is recommended to switch to the new name:
> `wirecloud.fiwarelabtheme`.


### URL_MIDDLEWARE_CLASSES
> (Dictionary; default: A middleware configuration dictionary)

A data structure containing the middleware configuration per URL group where the URL group name are the keys of the dictionary and the value should be a tuple of middleware classes to use for that group.

You should use this setting as replacement of the Django's MIDDLEWARE_CLASSES setting (See [Django's middleware documentation](https://docs.djangoproject.com/en/dev/topics/http/middleware/))

Currently available groups are "default", "api" and "proxy". For example, if you want to add a middleware class to the "api" group, you can use the following code:

```python
URL_MIDDLEWARE_CLASSES['api'] += ('my.middleware.module.MyMiddlware',)
```


### WIRECLOUD_HTTPS_VERIFY
> *new in WireCloud 0.7.0*
>
> (Boolean or String, default: `True`)

Set `WIRECLOUD_HTTPS_VERIFY` to `False` if you want WireCloud not validate HTTPS
certificates. If this setting is `True` (the default), WireCloud will verify
https certificates using the CA certificates bundled with python requests or
using the certificates provided by the system (this depends on the procedure
followed for installing the python requests module). You can also provide a path
to a CA bundle file to use instead (e.g.
`WIRECLOUD_HTTPS_VERIFY = "/etc/ssl/certs/ca-certificates.crt"`).


## Django configuration

The `settings.py` file allows you to set several options in WireCloud. If
`DEBUG` is `False` you will need to collect WireCloud static files using the
following command and answering 'yes' when asked:

    $ python manage.py collectstatic

In addition, you should serve the static files with a fast performance http
server like [Apache](http://httpd.apache.org/), [Nginx](http://nginx.org/),
[Gunicorn](http://gunicorn.org/), etc. We provide documentation on
[how to serve WireCloud using Apache 2](#running-wirecloud-using-apache-2).
Anyway, if you want to use any of the other http servers (e.g using Gunicorn),
Django provides
[documentation on how to do it](https://docs.djangoproject.com/en/dev/howto/deployment/).

Finally, you can compress CSS and JavaScript code files for better performance
using the following command:

    $ python manage.py compress --force

> **NOTE**: Don't forget to rerun the collectstatic and compress commands each
> time the WireCloud code is updated, this include each time a WireCloud plugin
> or Django app is enabled/disabled and when the default theme is changed.


## Advanced configurations

### Installing the WireCloud Pub Sub add-on

The development of the Pub Sub add-on is carried out at they own [github
repository](https://github.com/conwetlab/wirecloud-pubsub). You can always find
the latest information about how to install and use it on the main page of the
repository.
{'fraction_non_alphanumeric': 0.07700474361870341, 'fraction_numerical': 0.006392590919358482, 'mean_word_length': 4.0176810608636515, 'pattern_counts': {'":': 0, '<': 15, '<?xml version=': 0, '>': 112, 'https://': 26, 'lorem ipsum': 0, 'www.': 6, 'xml': 4}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7118862', 'n_tokens_mistral': 12238, 'n_tokens_neox': 11555, 'n_words': 5807}