120 lines
5.1 KiB
Markdown
120 lines
5.1 KiB
Markdown
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.
|
||
|
||
|
||
## 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).
|