pub-solar/obs-portal
5
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

Move and unify readme

Browse source
This commit is contained in:
Paul Bienkowski 2021-02-17 22:49:27 +01:00
parent 1fbd471341
commit 146c5e8e66
3 changed files with 124 additions and 170 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

124
README.md Normal file
View file

@ -0,0 +1,124 @@
# 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, as well as track management and
settings for the individual users.
The backend API for the [OpenBikeSensor](https://openbikesensor.org/) Web App.
## 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/) onto your machine, and cloning
the repository, all you need to do is:
```bash
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 `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 log -f api
```

100
api/README.md
View file

@ -1,100 +0,0 @@
# OpenBikeSensor Web API
The backend API for the [OpenBikeSensor](https://openbikesensor.org/) Web App.
## Direct setup
### Requirements
* A working installation of npm and node.js - get the latest node.js LTS
release at [the node.js homepage](https://nodejs.org/en/) and verify it's
working via `node -v` and `npm -v` in a command prompt of your choice. At
least node version 10.x is required.
* A working installation of [Docker](https://www.docker.com) for the
containerized MongoDB. Alternatively, you can set up your own MongoDB
elsewhere.
### First start
To get started you first need to download all dependencies in the project's
root folder:
npm install
Next up we have to run a MongoDB instance. The following command uses docker,
it assumes you have the docker daemon installed and running. Working with
docker might require root privileges, depending on your docker setup, so you
might want to prefix the following command with `sudo`:
npm run mongo:start
The development server will be accessible at `http://localhost:3000/api` after
starting it like this:
npm run dev
To stop the database when you're done developing, run (potentially with sudo):
npm run mongo:stop
## Updating
If you run this through cloning the git and setting it up as a systemctl
service, you can follow this procedure to update the application:
```bash
sudo systemctl stop obsApp.service
git pull
npm install
npm run migrate:up
sudo systemctl start obsApp.service
```
## Docker setup
If you have docker and don't want to bother installing Node.js on your machine,
you can run the application inside docker as well:
docker-compose up -d
This will first build the `obs-api` image, which contains all the steps
outlined above, and then run the services, both a mongodb and the api itself,
in docker containers. Interaction with the processes is different though,
expect other guides or commands to work differently in this type of setup.
## 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
```

70
frontend/README.md
View file

@ -1,70 +0,0 @@
# Getting Started with Create React App
This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
## Available Scripts
In the project directory, you can run:
### `yarn start`
Runs the app in the development mode.\
Open [http://localhost:3000](http://localhost:3000) to view it in the browser.
The page will reload if you make edits.\
You will also see any lint errors in the console.
### `yarn test`
Launches the test runner in the interactive watch mode.\
See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information.
### `yarn build`
Builds the app for production to the `build` folder.\
It correctly bundles React in production mode and optimizes the build for the best performance.
The build is minified and the filenames include the hashes.\
Your app is ready to be deployed!
See the section about [deployment](https://facebook.github.io/create-react-app/docs/deployment) for more information.
### `yarn eject`
**Note: this is a one-way operation. Once you `eject`, you can’t go back!**
If you aren’t satisfied with the build tool and configuration choices, you can `eject` at any time. This command will remove the single build dependency from your project.
Instead, it will copy all the configuration files and the transitive dependencies (webpack, Babel, ESLint, etc) right into your project so you have full control over them. All of the commands except `eject` will still work, but they will point to the copied scripts so you can tweak them. At this point you’re on your own.
You don’t have to ever use `eject`. The curated feature set is suitable for small and middle deployments, and you shouldn’t feel obligated to use this feature. However we understand that this tool wouldn’t be useful if you couldn’t customize it when you are ready for it.
## Learn More
You can learn more in the [Create React App documentation](https://facebook.github.io/create-react-app/docs/getting-started).
To learn React, check out the [React documentation](https://reactjs.org/).
### Code Splitting
This section has moved here: [https://facebook.github.io/create-react-app/docs/code-splitting](https://facebook.github.io/create-react-app/docs/code-splitting)
### Analyzing the Bundle Size
This section has moved here: [https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size](https://facebook.github.io/create-react-app/docs/analyzing-the-bundle-size)
### Making a Progressive Web App
This section has moved here: [https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app](https://facebook.github.io/create-react-app/docs/making-a-progressive-web-app)
### Advanced Configuration
This section has moved here: [https://facebook.github.io/create-react-app/docs/advanced-configuration](https://facebook.github.io/create-react-app/docs/advanced-configuration)
### Deployment
This section has moved here: [https://facebook.github.io/create-react-app/docs/deployment](https://facebook.github.io/create-react-app/docs/deployment)
### `yarn build` fails to minify
This section has moved here: [https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify](https://facebook.github.io/create-react-app/docs/troubleshooting#npm-run-build-fails-to-minify)