aux
/
keyserver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Improve documentation with more details to get started

This commit is contained in:
Stefan 2021-07-04 16:13:16 +02:00 committed by Thomas Oberndörfer
parent f118ec64b0
commit cd62e63cc2
1 changed files with 62 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

86
README.md
View File

@ -155,13 +155,17 @@ DELETE /api/v1/key?keyId=b8e4105cc9dedc77 OR ?email=user@example.com
GET /api/v1/key?op=verifyRemove&keyId=b8e4105cc9dedc77&nonce=6a314915c09368224b11df0feedbc53c GET /api/v1/key?op=verifyRemove&keyId=b8e4105cc9dedc77&nonce=6a314915c09368224b11df0feedbc53c
``` ```
# Language & DB
The server is written is in JavaScript ES7 and runs on [Node.js](https://nodejs.org/) v8+.
It uses [MongoDB](https://www.mongodb.com/) v3.2+ as its database.
# Development # Getting started
## Installation
The server is written is in JavaScript ES7 and runs on [Node.js](https://nodejs.org/) v8+. It uses [MongoDB](https://www.mongodb.com/) v3.2+ as its database. ### Node.js (Mac OS)
## Install Node.js (Mac OS)
This is how to install node on Mac OS using [homebrew](http://brew.sh/). For other operating systems, please refer to the [Node.js download page](https://nodejs.org/en/download/). This is how to install node on Mac OS using [homebrew](http://brew.sh/). For other operating systems, please refer to the [Node.js download page](https://nodejs.org/en/download/).
@ -170,7 +174,7 @@ brew update
brew install node brew install node
``` ```
## Setup local MongoDB (Mac OS) ### MongoDB (Mac OS)
This is the installation guide to get a local development installation on Mac OS using [homebrew](http://brew.sh/). For other operating systems, please refer to the [MongoDB Getting Started Guide](https://docs.mongodb.com/getting-started/shell/). This is the installation guide to get a local development installation on Mac OS using [homebrew](http://brew.sh/). For other operating systems, please refer to the [MongoDB Getting Started Guide](https://docs.mongodb.com/getting-started/shell/).
@ -186,7 +190,7 @@ Now the mongo daemon should be running in the background. To have mongo start au
brew services start mongodb brew services start mongodb
``` ```
Now you can use the `mongo` CLI client to create a new test database. **The username and password used here match the ones in the `config/development.js` file. Be sure to change them for production use**: Now you can use the `mongo` CLI client to create a new test database. The username and password used here match the ones in the `config/development.js` file. **Be sure to change them for production use**:
```shell ```shell
mongo mongo
@ -194,31 +198,46 @@ use keyserver-test
db.createUser({ user:"keyserver-user", pwd:"trfepCpjhVrqgpXFWsEF", roles:[{ role:"readWrite", db:"keyserver-test" }] }) db.createUser({ user:"keyserver-user", pwd:"trfepCpjhVrqgpXFWsEF", roles:[{ role:"readWrite", db:"keyserver-test" }] })
``` ```
## Setup SMTP user ### Dependencies
The key server uses [nodemailer](https://nodemailer.com) to send out emails upon public key upload to verify email address ownership. To test this feature locally, open the `config/development.js` file and change the `email.auth.user` and `email.auth.pass` attributes to your Gmail test account. Make sure that `email.auth.user` and `email.sender.email` match. Otherwise the Gmail SMTP server will block any emails you try to send. Also, make sure to enable `Allow less secure apps` in the [Gmail security settings](https://myaccount.google.com/security#connectedapps). You can read more on this in the [Nodemailer documentation](https://nodemailer.com/using-gmail/).
For production you should use a service like [Amazon SES](https://aws.amazon.com/ses/), [Mailgun](https://www.mailgun.com/) or [Sendgrid](https://sendgrid.com/solutions/transactional-email/). Nodemailer supports all of these out of the box.
## Install dependencies and run tests
```shell ```shell
npm install && npm test npm install
``` ```
## Start local server ## Configuration
```shell Configuration settings may be provided as environment variables. The files in the config directory read the environment variables and define configuration values for settings with no corresponding environment variable. Warning: Default settings are only provided for a small minority of settings in these files (as most of them are very individual like host/user/password)!
npm start
```
If settings are configured in multiple places, the priority ranking is as follows (individually for each setting):
1. Environment variable
2. config/production.js or config/development.js (depending on NODE_ENV)
3. config/default.js
### Development
# Production If you don't use environment variables to configure settings, create `config/development.js` and use `config/default.js` as a template. Creating `development.js` instead of just editing `config/default.js` is recommended to prevent accidental commits of locally used settings.
The `config/development.js` file can be used to configure a local development installation. For production use, the following environment variables need to be set: ### Production
* NODE_ENV=production For production use, settings configuration with environment variables is recommended as `NODE_ENV=production` is REQUIRED to be set as environment variable to instruct node.js to adapt e.g. logging to production use.
*Other settings you may also configure within `config/production.js` and use `config/default.js` as a template; but ensure then the environment variable `NODE_ENV=production` or `production.js` will not be read!*
### Settings
Available settings with its environment-variable-names, possible/example values and meaning (if not self-explainable). Defaults **bold**:
* NODE_ENV=development|production
(no default + needs to be set as environment variable!)
* LOG_LEVEL=**silly**|error|warn|info|debug
* PORT=**8888**
(application server port)
* HTTPS_UPGRADE=true
(upgrade HTTP requests to HTTPS and use [HSTS](https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security))
* HTTPS_KEY_PIN=base64_encoded_sha256
(optional, see [HPKP](https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning))
* HTTPS_KEY_PIN_BACKUP=base64_encoded_sha256
(optional, see [HPKP](https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning))
* MONGO_URI=127.0.0.1:27017/test_db * MONGO_URI=127.0.0.1:27017/test_db
* MONGO_USER=db_user * MONGO_USER=db_user
* MONGO_PASS=db_password * MONGO_PASS=db_password
@ -227,13 +246,32 @@ The `config/development.js` file can be used to configure a local development in
* SMTP_TLS=true * SMTP_TLS=true
* SMTP_STARTTLS=true * SMTP_STARTTLS=true
* SMTP_PGP=true * SMTP_PGP=true
(encrypt verification message with public key (allows to verify presence + usability of private key at owner of the mail-address))
* SMTP_USER=smtp_user * SMTP_USER=smtp_user
* SMTP_PASS=smtp_pass * SMTP_PASS=smtp_pass
* SENDER_NAME="OpenPGP Key Server" * SENDER_NAME="OpenPGP Key Server"
* SENDER_EMAIL=noreply@example.com * SENDER_EMAIL=noreply@example.com
* HTTPS_UPGRADE=true (upgrade HTTP requests to HTTPS and use [HSTS](https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security)) * PUBLIC_KEY_PURGE_TIME=**30**
* HTTPS_KEY_PIN=base64_encoded_sha256 (optional, see [HPKP](https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning)) (number of days after which uploaded keys are deleted if they have not been verified)
* HTTPS_KEY_PIN_BACKUP=base64_encoded_sha256 (optional, see [HPKP](https://developer.mozilla.org/en-US/docs/Web/Security/Public_Key_Pinning))
### Notes on SMTP
The key server uses [nodemailer](https://nodemailer.com) to send out emails upon public key upload to verify email address ownership. To test this feature locally, configure `SMTP_USER` and `SMTP_PASS` settings to your Gmail test account. Make sure that `SMTP_USER` and `SENDER_EMAIL` match. Otherwise the Gmail SMTP server will block any emails you try to send. Also, make sure to enable `Allow less secure apps` in the [Gmail security settings](https://myaccount.google.com/security#connectedapps). You can read more on this in the [Nodemailer documentation](https://nodemailer.com/using-gmail/).
For production you should use a service like [Amazon SES](https://aws.amazon.com/ses/), [Mailgun](https://www.mailgun.com/) or [Sendgrid](https://sendgrid.com/solutions/transactional-email/). Nodemailer supports all of these out of the box.
## Run tests
```shell
npm test
```
## Start local server
```shell
npm start
```