manuscripts.io

Requirements

• Node.js
• Docker

Installation

npm install

Configuration variables should be set in .env

Run the app

Run Postgres and API server in Docker:

./bin/run-dockerized-app.sh

The API will be available at http://127.0.0.1:3000/

Seed the app

./bin/seed-app.sh

This will create 2 users, 2 projects with a manuscript

Test the app

Run Postgres and the test runner in Docker:

./bin/run-dockerized-tests.sh

Run Postgres in Docker, and run the tests locally:

./bin/run-dockerized-db.sh
npm run test

You may need to edit your hosts file:

127.0.0.1 postgres

Development

Run Postgres in Docker, and run the API server locally:

./bin/run-dockerized-db.sh
npm run dev

Debugging with VS Code

Run Postgres in Docker, and run the tests locally:

./bin/run-dockerized-db.sh

You will now be able to use of the three launch configurations for VS Code:

• "Launch": runs the API server locally in the debugger.
• "Unit Tests": runs unit tests in the debugger.
• "Integration Tests": runs integration tests in the debugger.

All of these launch configurations take the .env.example environment variables and modify them to prepare the environment for local execution.

Developer Notes

When a new environment/configuration variable is added in the code, make sure to add it to the following places:

a) In .env.example file

b) In docker/utils/templates/docker-compose.yml.ejsfile. Make sure to add it under respective service as well as under test_runner configuration

Configuration

The service is configured using environment variables and/or a .env file placed at the root of the repository.

APP_BASE_URL

The *client* app base URL (the manuscripts-frontend instance) corresponding to this service.

APP_FROM_EMAIL

The email address from which emails sent by the service are sent.

APP_JWT_SECRET

A cryptographic secret used for JWT signatures.

APP_PORT

The port to which the service should bind to serve from.

APP_CLIENT_APPLICATIONS

A semi-colon separated list of acceptable client details, with each field comma separated including an optional secret. It corresponds to Application Id, Application Secret, Application Name. (e.g. "com.manuscripts.Manuscripts,foobar,Manuscripts;io.manuscripts,,Manuscripts.io").

APP_DATABASE_URL

The postgres database connection url

APP_USER_BUCKET

The name of a database bucket for user account credentials and other user auth state.

APP_DATA_BUCKET

The name of a database bucket for user owned project data.

NODE_ENV

Express.js specific environment variable whose acceptable values are enforced by manuscripts-api to be "development" and "production" (see Express.js docs re production specific behaviour).

APP_STORE_ONLY_SSL_TRANSMITTED_COOKIES

If set to '0', cookies transmitted over SSL encrypted connections will be stored (see "Set cookie security options" in Express.js documentation for more info), also the samesite cookie will be Strict

APP_ALLOWED_CORS_ORIGINS

Allowed CORS origins for manuscripts-api and the Sync Gateway.

APP_SKIP_ACCOUNT_VERIFICATION

If set to '1', skip the account verification step at account creation.

APP_ALLOW_ANONYMOUS_USERS

If set to '1', enables endpoint for returning connection credentials (including a Sync Gateway session cookie) for an anonymous user.

APP_HASH_SALT_ROUNDS

An optional value for the bcrypt password salt rounds used for storing passwords.

APP_CONTAINER_TOKEN_SCOPES

An array of semicolon separated records to describe scopes for which the server can issue access tokens in JWT form: fields are comma separated, denoting for each record: scope name,UTF8 encoded secret or base64 encoded PEM formatted private key,empty string (if symmetric secret is used) or a base64 encoded PEM formatted public key,expiry in minutes

Access Control

In the past, access control happened via a sync function through the SyncGateway API, with specific semantics. Those semantics have been replaced with a proceedWithAccess call, and the main body of the sync function remains (mostly) the same. Whenever a repository (that extends SGRepository) function is called with a userId parameter, access control logic executes.

requireAdmin has been removed because there is no SG Admin API anymore

When manuscripts-json-schema changes, we must redeploy the API in order to build the correct json schema validator function

API DOCS

Available at http://127.0.0.1:3000/api/v1/docs only on non-production envs

To regenerate the docs:

npm run docs