Installation
Amber is a system of several applications:
Amber server: Business layer over the database: users, groups, studies, forms, case records etc. are all defined in this application and their access require authentication and authorization. It is only accessible via an API.
Amber Studio web app: Content management web application, using data and services of the Amber server
Amber Collect web app: Case report data collection web app, using data and services of the Amber server
Amber Visit web app: Interview data collection web app, using data and services of the Amber server
These applications are written in JavaScript.
Requirements
Server Hardware Requirements
Component |
Requirement |
---|---|
CPU |
Recent server-grade or high-end consumer-grade processor |
Disk space |
8GB or more. |
Memory (RAM) |
Minimum: 4GB, Recommended: >4GB |
Server Software Requirements
Amber server and apps are pure JavaScript software based on nodejs (Amber) and Quasar (Amber Studio and Amber Collect). Despite it could be possible to set up a native runtime environment, we recommend to use a containerized one (Docker), to facilitate to customization and the deployment of the software applications.
The database that is used by Amber server is MongoDB which can also be deployed from a container.
Then recommended runtime environment is:
Software |
Documentation |
Usage |
---|---|---|
Docker Engine |
Docker runtime environment |
|
Docker Compose |
Docker compose plugin |
Install
Docker Images Installation
Because the Amber system is composed of different parts (server and client applications), these need to be integrated with each other for the specific site where they will be deployed.
The set up of the different Docker images of Amber is described in the amber-template project.
The steps to follow are:
Download or clone the
amber-template
repository,Define the Amber (server and apps) parts (configuration and/or source files) to customize,
Use the
Docker Compose
tool to build and run these images in your specific environment.
The environment variables that are exposed by the amber
image are:
Environment Variable |
Description |
---|---|
|
Node cluster count, defaults to all available CPU cores |
|
JWT issuer |
|
Encryption key |
|
Secret string for the encryption’s initial vector, |
|
JWT audience |
|
The allowed API keys (comma separated values) for triggering backround tasks execution, |
|
Comma separated client urls, for the CORS policy |
|
Amber Studio app url, to be included in the notification emails |
|
Amber Collect app url, to be included in the notification emails |
|
Amber Visit app url, to be included in the notification emails |
|
The MongoDB connection string |
|
Whether the patient/participant data should be encrypted in the database |
|
Number of minutes during which the onetime password (OTP) sent by email is valid. Default is 5; when set to 0, the email-based onetime password is deactivated. This does not apply to the time-based onetime password (TOTP) procedure, which can be activated per user. |
|
The reCAPTCHA v3 secret key. |
|
List of email domains that are allowed to signup. Use ‘*’ for wild card. Default is all. |
|
List of email domains that are NOT allowed to signup. Use ‘*’ for wild card. Default is none. |
|
The Gmail user name for the notification service (optional, only if Gmail transport service is used) |
|
The Gmail user password for the notification service (optional, only if Gmail transport service is used) |
|
The Sendinblue API key for the notification service (optional, only if Sendinblue transport service is used) |
|
The SMTP server host |
|
The SMTP server port |
|
The SMTP server name |
|
Whether the SMTP connection should use SSL |
|
Whether the SMTP connection should use TLS (when secure is false) |
|
Enable SMTP logging |
|
Enable SMTP debug by sending log events |
|
The SMTP server user |
|
The SMTP server user’s password |
|
The automated sender email address, |
|
User seeding when there is no administrator in the database |
|
User seeding when there is no administrator in the database |
|
Logger level (error` warn` info` verbose` debug` silly` etc. (see [winstonjs](https://github.com/winstonjs/winston))), default is info |
|
File logger path |
|
File logger level when LOG_FILE is specified, default is LOG_LEVEL |
|
Name of the config file to be merged with the default one (e.g. production) |
The environment variables that are exposed by the amber-studio
, amber-collect
and amber-visit
images are:
Environment Variable |
Description |
---|---|
|
The URL to the Amber server. |
|
The reCAPTCHA v3 site key. If not provided, the Sign Up page will not be activated. |
Upgrade
The upgrade procedures are handled by the application itself.
Troubleshooting
If you encounter an issue during the installation and you can’t resolve it, please report it in our Amber Issue Tracker.