OpenBikeSensor Portal

This repository contains the source code required to run the OpenBikeSensor data collection portal. It is separated into components:

api: The backend service, written in JavaScript for Node.js, using express.js, and a MongoDB for metadata storage.
frontend: A React single-page application that allows access to the data, provides summaries and visualizations, and lets users adjust settings and manage and publish their tracks.

Development setup

We've moved the whole development setup into Docker to make it easy for everyone to get involved. After sucessfully installing Docker Engine as well as Docker Compose onto your machine, and cloning the repository, all you need to do is:

docker-compose up -d

If this does not work, please open an issue and describe the problem you're having, as it is important to us that onboarding is super easy :)

Your frontend should be running at http://localhost:3001 and the API at http://localhost:3000 -- but you probably only need to access the frontend for testing. The frontend dev server also proxies all unknown requests to the API, so the frontend always just requests data at its own URL.

Running without docker

If you don't like docker, or want to run this in production without it, you can do so as well. Our Docker setup is simply a slight wrapper around very simple JavaScript packages that you can install yourself as usual, with npm install. The API can be started with npm start inside its folder. The frontend development server uses npm start as well, while building a production version of the frontend happens with npm run build.

To connect the parts together, please have a look at what we're doing in the "official" setup of docker, i.e. in docker-compose.yaml, the Dockerfiles and in the respective package.json of the service. If you've done this kind of thing before, it's not that hard. Otherwise, ask on Slack and there will be somebody to help you ;)

Running in production

You are advised not to use the dockerized mongodb service and instead do a proper MongoDB setup on a server that is backed up and secured.

You can run the API in docker, but it is prefered to run it as a restricted user in its own directory somewhere where it cannot escape ;)

The frontend should be built using npm run build and then served from a proper web server, such as nginx or apache. See the instructions at create-react-app concerning deployment of an app.

You are advised to virtualize your server for security reason, and separate this whole application from other parts of your server system.

Also please install a reverse proxy that terminates TLS for you and handles certificates. We do not support TLS directly in the application, instead, please use this prefered method. This reverse proxy can also handle static file serving for the frontend, no need for two separate server processes.

Migrating

Sometimes your database will have to be migrated. The docker setup should do this automatically, but if it does not work, you can run the following commands:

# if running locally
(cd api/; npm run migrate:up)

# if running in docker
docker-compose run --rm api npm run migrate:up

Custom MongoDB installation

If you have your own MongoDB instance running somewhere, you can set the environment variable MONGODB_URL when starting the server, and it will read that URL for connecting.

export MONGODB_URL=mongodb://user:password@mongodb.example.com/obs-app-database

This does not work when using docker-compose, in that case, you will have to modify the docker-compose.yaml to include that URL.

E-Mail Setup

By default in development mode mails are not sent, but instead the mail data is logged to the console. This can be overriden with the --devSendMails flag if you start the application like so: npm run dev -- --devSendMails.

Mails are also always sent in production mode!

For actually sending e-mails the mailserver, sender, user and password for the SMTP server need to be specified as environment variables:

MAILUSER -- the smtp mailbox login name
MAILPW -- password for the mailbox
MAILSERVER -- the hostname of the SMTP server, e.g. mail.example.com
MAILSENDER -- sender name, e.g. noreply@example.com

Full command example:

MAILSERVER=mail.example.com MAILSENDER=noreply@example.com \
    MAILUSER=my_mail_login MAILPW=hunter2 \
    npm run dev -- --devSendMails

All of this of course is not too important if you're developing locally. To get to the logged email content that would have been sent, check your docker log:

docker-compose log -f api

nielsole / portal