101 lines
3.2 KiB
Markdown
101 lines
3.2 KiB
Markdown
# 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
|
|
```
|