171 lines
6.9 KiB
Markdown
171 lines
6.9 KiB
Markdown
# OpenBikeSensor Portal
|
|
|
|
This repository contains the source code required to run the
|
|
[OpenBikeSensor](https://openbikesensor.org) 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.
|
|
|
|
## Clone the Project
|
|
|
|
First of all, you must clone this project. This project uses submodules,
|
|
thus ensure, that they are cloned as well:
|
|
|
|
```bash
|
|
git clone --recursive https://github.com/openbikesensor/portal
|
|
|
|
# ... or if you forgot the --recursive argument, you can run this in the
|
|
# repository's directory later:
|
|
git submodule update --init --recursive
|
|
```
|
|
|
|
## Production setup
|
|
|
|
**Note:** There is now a guide for a dockerized deployment in the
|
|
[deployment](deployment) folder.
|
|
|
|
You should be familiar with managing a Linux server. If not, find a suitable
|
|
guide first. This will only give a rough outline of the steps to take, you must
|
|
make sure to properly set up and secure your server yourself.
|
|
|
|
1. Create a user for running the application. It is not recommended to run as a
|
|
user that is also used for other things. Do not run as root!
|
|
2. Clone the repository.
|
|
3. Install `node` of at least version 15, and also `npm`. You can use the
|
|
[Node Version Manager (nvm)](https://github.com/nvm-sh/nvm), since this project
|
|
contains a `.nvmrc`. Just run `nvm install` followed by `nvm use`.
|
|
4. Run `npm ci` in the `api` and `frontend` directories to install dependencies.
|
|
5. Install and configure a MongoDB somewhere.
|
|
6. Copy `api/config.json.example` to `api/config.json` and change it to suit
|
|
your setup. Make sure to only use https URLs. Generate secure secrets.
|
|
Customize client IDs.
|
|
7. Copy `frontend/src/config.json.example` to `frontend/src/config.json` and
|
|
adjust.
|
|
8. Run `npm run build` in the frontend directory. This needs to be done after
|
|
changing the config, so if you did something wrong, re-run the build. If you
|
|
run your frontend on a non-root URL, run the build with the
|
|
`PUBLIC_URL=/prefix` environment variable.
|
|
9. Create a systemd-user service, or use tmux, or do whatever you like to start
|
|
the API service (`npm start` in `api/` directory). It should run as the
|
|
dedicated user, and expose `127.0.0.1:3000`. Use `PORT` environment variable
|
|
if you want to change the port. Make sure the service starts with
|
|
environment `NODE_ENV=production`, too.
|
|
10. Configure nginx or your reverse-proxy of choice to forward API requests to
|
|
the API port, and serve static files from the `frontend/build/` folder.
|
|
|
|
## 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](https://docs.docker.com/engine/install/) as well as [Docker
|
|
Compose](https://docs.docker.com/compose/install/) onto your machine, and
|
|
cloning the repository, all you need to do is:
|
|
|
|
```bash
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
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 `Dockerfile`s
|
|
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](http://cra.link/deployment).
|
|
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
docker-compose logs -f api
|
|
```
|