SmartCitizen API

Documentation

• Production API - https://api.smartcitizen.me
• Basic Map Example - https://api.smartcitizen.me/examples/map (map)
• OAuth 2.0 (Implicit Grant) Example - http://example.smartcitizen.me (smartcitizen-oauth-example)

Installing Locally

Docker quickstart

1. Copy the environment file, and edit variables, domain name, etc

   cp env.example .env

2. Start basic services (recommended)

   In a new terminal window do:

   docker-compose up app db

   See the docker-compose.yml file depends_on: section to see which containers depend on which.

   Available containers:

   • app - Rails app
   • db - Postgres
   • redis
   • web container which tries to get a certificate with Lets Encrypt.
   • mqtt EMQ + management interface on http://localhost:18083 admin:public
   • mqtt-task a rake task which subscribes to the mqtt service
   • sidekiq
   • kairos - Time series database on Cassandra
   • cassandra-1 - Stores the data

   Start ALL of them (not recommended) with:

   docker-compose up

3. (OPTIONAL) Start Cassandra cluster of 3 nodes

   If you want to start Kairos with 3 Cassandra cluster with 3 nodes:

   • Uncomment the other 2 cassandras in docker-compose.yml file

   • Edit the file scripts/conf/kairosdb.properties and change the following line:

     kairosdb.datastore.cassandra.cql_host_list=cassandra-1

     docker-compose up kairos cassandra-1 cassandra-2 cassandra-3

4. Create the database (first time only)

   If you need to perfom many operations, it might be better to bash into the container:

   docker-compose exec app bash

   and from here you can do

   bin/rails db:create

   bin/rails db:schema:load

   bin/rails db:seed

   Or you can run them all at once with: docker-compose exec app bin/rails db:setup

5. Removing everything

   Remove all containers + data volumes with:

   docker-compose down -v

Linux (Tested on Ubuntu 16.04)

apt-get install libmysqlclient-dev

Redis and Postgresql

brew tap homebrew/services

brew install redis postgresql

brew services start redis

brew services start postgresql

KairosDB

wget https://github.com/kairosdb/kairosdb/releases/download/v1.0.0/kairosdb-1.0.0-1.tar.gz

tar -zxvf kairosdb-1.0.0-1.tar.gz

./kairosdb/bin/kairosdb.sh run

SmartCitizen

git clone https://github.com/fablabbcn/smartcitizen

cd smartcitizen

bundle install

bundle exec bin/rails s

Deploying

Using Docker

1. SSH into the server
2. git pull
3. docker-compose build
4. docker-compose up -d

Cassandra

Documentation and scripts to deploy and operate cassandra in production are available on scripts/cassandra.

Backup and restore

In the scripts/ folder there are backup and restore scripts for docker postgres.

Working with MQTT locally (no Docker)

1. Start an mqtt server like mosquitto

2. Subscribe to a topic (useful for debugging):

   mosquitto_sub --topic '$queue/device/sck/abcdef/hello'

3. Start the mqtt rake task:

   bundle exec rake mqtt:sub mqtt_host=localhost

4. Publish a packet

   mosquitto_pub --message abcdef --topic '$queue/device/sck/abcdef/hello'

Working with MQTT and WebSockets via Docker

If running on Docker, there should be a EMQ Dashboard running on http://localhost:18083 (Log in with admin:public)

The following will send a message from the app container to the mqtt container:

1. Subscribe to a Websocket topic called "test" in the Dashboard http://localhost:18083/#/websocket

2. Access the rails console inside the app container:

   docker-compose exec app bin/rails console

3. Send a message to the test topic:

   MQTT::Client.connect('mqtt').publish('test', 'this is the message')

Tools / Scripts

We supply a nodejs helper post-readings.js tool to test sending massive amounts of data. Just like uploading a CSV file with a lot of readings.

To learn how to use it, do ./post-readings.js

Versioning

Currently using this tool to manually handle versioning: https://github.com/gregorym/bump

Use this command to update the VERSION file + create a git tag

bump patch --tag

Then push the git tag with:

git push --tags

Funding

This work has received funding from the European Union's Horizon 2020 research and innovation program under the grant agreement No. 689954