From b8506bf75a908e5ed5f1085d5350336359ee4587 Mon Sep 17 00:00:00 2001 From: Paul Bienkowski Date: Tue, 17 Nov 2020 17:54:46 +0100 Subject: [PATCH] chore: update README to reflect docker startup process, also: formatting --- README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 85 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3f1ff67..0538f7f 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,103 @@ # OpenBikeSensor Web API + The backend API for the [OpenBikeSensor](https://zweirat-stuttgart.de/projekte/openbikesensor/) Web App. -## Running it -### 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. +## Direct setup -A working installation of [Docker](https://www.docker.com) for the used containerized MongoDB. +### 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 need to download all used packages with `npm i` in the project's root folder first. -Next up is our local MongoDB. This uses docker but can be conveniently started via `sudo npm run mongo:start` (at least in Ubuntu Linux). +To get started you first need to download all dependencies in the project's +root folder: -Afterwards the dev server is started with `npm run dev` and can be called via `http://localhost:3000/api`. + npm install -To completely stop the project after running it a call to `sudo npm run mongo:stop` is necessary. +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`: -### Running the tests -Just execute `npm run test` while both the node.js server and the MongoDB are up and running. + npm run mongo:start -Warning: At the moment (2020-09-29) there are no tests. +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 + +## 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. + + +## Usage ### Uploading a track for test purposes -Uploading a track to the local server requires multiple steps, as uploading is not possible via the dummy upload form in the corresponding web app yet: -- Create a user in the web app and copy the user id, which can be found at (http://localhost:4200/settings) as "API key" -- Import the [Postman](https://www.postman.com) script "add-track.json" from the "postman-examples" into Postman -- In each of the three requests add your user id in the "Pre-request script" tab as the value for the "UserId" variable -- As tracks have to be split into smaller parts to get a working upload from the sensor you have to run the three requests in the order of: begin -> add -> end -- View your freshly uploaded track at (http://localhost:4200) -> Home -> Your feed + +Uploading a track to the local server requires multiple steps, as uploading is +not possible via the dummy upload form in the corresponding web app yet: + +- Create a user in the web app and copy the user id, which can be found at + (http://localhost:4200/settings) as "API key" +- Import the [Postman](https://www.postman.com) script "add-track.json" from + the "postman-examples" into Postman +- In each of the three requests add your user id in the "Pre-request script" + tab as the value for the "UserId" variable +- As tracks have to be split into smaller parts to get a working upload from + the sensor you have to run the three requests in the order of: begin -> add + -> end +- View your freshly uploaded track at (http://localhost:4200) -> Home -> Your + feed ### Sending E-Mails -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`. + +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. The username is read from `MAILUSER`, and the password is read from `MAILPW`, Mailserver is read from 'MAILSERVER' and the sender name from 'MAILSENDER', so in local development startup would like something like this (at least in Linux): `MAILSERVER=mail.my-domain.de MAILSENDER=noreply@whatever.de MAILUSER=myuser MAILPW=supersecurepassword npm run dev -- --devSendMails`. +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