flatisfy/doc/0.getting_started.md

Getting started
===============

**Important**: Flatisfy relies on [Weboob](http://weboob.org/) to fetch
housing posts from housing websites. Then, you should install the [`devel`
branch](https://git.weboob.org/weboob/devel/) and update it regularly,
especially if Flatisfy suddenly stops fetching housing posts.

**Note**: For the moment, it requires [this MR on
Weboob](https://git.weboob.org/weboob/devel/merge_requests/31) which has not
yet been merged.

## TL;DR

1. Clone the repository.
2. Install required Python modules: `pip install -r requirements.txt`.
3. Init a configuration file: `python -m flatisfy init-config > config.json`.
   Edit it according to your needs (see below).
4. Build the required data files:
   `python -m flatisfy build-data --config config.json`.
5. Use it to `fetch` (and output a filtered JSON list of flats) or `import`
   (into an SQLite database, for the web visualization) a list of flats
   matching your criteria.
6. Install JS libraries and build the webapp:
   `npm install && npm run build:dev` (use `build:prod` in production).
7. Use `python -m flatisfy serve --config config.json` to serve the web app.


## Available commands

The available commands are:

* `init-config` to generate an empty configuration file, either on the `stdin`
  or in the specified file.
* `build-data` to rebuild OpenData datasets.
* `fetch` to load and filter housings posts and output a JSON dump.
* `filter` to filter again the flats in the database (and update their status)
  according to changes in config. It can also filter a previously fetched list
  of housings posts, provided as a JSON dump (with a `--input` argument).
* `import` to import and filter housing posts into the database.
* `serve` to serve the built-in webapp with the development server. Do not use
  in production.


### Common arguments

You can pass some command-line arguments to Flatisfy commands, common to all the available commands. These are

* `--help`/`-h` to get some help message about the current command.
* `--data-dir DIR` to overload the `data_directory` value from config.
* `--config CONFIG` to use the config file located at `CONFIG`.
* `--passes [0, 1, 2, 3]` to overload the `passes` value from config.
* `--max-entries N` to overload the `max_entries` value from config.
* `-v` to enable verbose output.
* `-vv` to enable debug output.


## Configuration

List of configuration options:

* `data_directory` is the directory in which you want data files to be stored.
  `null` is the default value and means default `XDG` location (typically
  `~/.local/share/flatisfy/`)
* `max_entries` is the maximum number of entries to fetch.
* `passes` is the number of passes to run on the data. First pass is a basic
  filtering and using only the informations from the housings list page.
  Second pass loads any possible information about the filtered flats and does
  better filtering.
* `database` is an SQLAlchemy URI to a database file. Defaults to `null` which
  means that it will store the database in the default location, in
  `data_directory`.
* `navitia_api_key` is an API token for [Navitia](https://www.navitia.io/)
  which is required to compute travel times.
* `modules_path` is the path to the Weboob modules. It can be `None` if you
  want Weboob to use the locally pip-installed modules (default value).
* `port` is the port on which the development webserver should be
  listening (default to `8080`).
* `host` is the host on which the development webserver should be listening
  (default to `127.0.0.1`).
* `webserver` is a server to use instead of the default Bottle built-in
  webserver, see [Bottle deployment
  doc](http://bottlepy.org/docs/dev/deployment.html).
* `backends` is a list of Weboob backends to enable. It defaults to any
  available and supported Weboob backend.

_Note:_ In production, you can either use the `serve` command with a reliable
webserver instead of the default Bottle webserver (specifying a `webserver`
value) or use the `wsgi.py` script at the root of the repository to use WSGI.


### Constraints

You should specify some constraints to filter the resulting housings list,
under the `constraints` key. The available constraints are:

* `type` is the type of housing you want, either `RENT` (to rent), `SALE` (to
  buy) or `SHARING` (for a shared housing).
* `housing_types` is a list of house types you are looking for. Values can be
  `APART` (flat), `HOUSE`, `PARKING`, `LAND`, `OTHER` (everything else) or
  `UNKNOWN` (anything which was not matched with one of the previous
  categories).
* `area` (in m²), `bedrooms`, `cost` (in currency unit), `rooms`: this is a
  tuple of `(min, max)` values, defining an interval in which the value should
  lie. A `null` value means that any value is within this bound.
* `postal_codes` is a list of postal codes. You should include any postal code
  you want, and especially the postal codes close to the precise location you
  want.
* `time_to` is a dictionary of places to compute travel time to them.
  Typically,

  ```
  "time_to": {
    "foobar": {
        "gps": [LAT, LNG],
        "time": [min, max]
    }
  }
  ```

  means that the housings must be between the `min` and `max` bounds (possibly
  `null`) from the place identified by the GPS coordinates `LAT` and `LNG`
  (latitude and longitude), and we call this place `foobar` in human-readable
  form. Beware that `time` constraints are in **seconds**.


## Building the web assets

If you want to build the web assets, you can use `npm run build:dev`
(respectively `npm run watch:dev` to build continuously and monitor changes in
source files). You can use `npm run build:prod` (`npm run watch:prod`) to do
the same in production mode (with minification etc).