Before You Start

Before you start your development process within the CARE tool, please read this quick overview on prerequisites and your building options.

Tip

If you just want to get started real quick, check out the Development Build section below.

Software Prerequisites

CARE’s backend is running with Node.js and is built with npm. You will need to install them before you can start coding. While CARE is deployed in a docker container, for development you should run the dev build locally.

You also need Docker and docker-compose for building the various containers – both in dev and deployment mode. Please install all packages according to the official documentation:

Note

On Windows, you can use the make command with the GNU Make for Windows package. On newer windows systems, simply use winget install GnuWin32.Make and make it executable with set PATH=%PATH%;C:/Program Files (x86)/GnuWin32/bin.

Customizing Builds

Any commands for building components of CARE can be found in the top-most Makefile of the project. To see a full list of available commands run:

make help

Before running your first build commands, you may want to customize the environment variables for your specific needs. The environment variables are completely managed in the .env files at the top-most directory. For most parts, the default settings should work for you, but if you want to adapt ports and hosts these are the files to change. Also note that the initial admin account and password are stored here in cleartext.

.env-files

You need to adapt different env-files depending on whether you build for development (.env), for deployment (.env.main), or for testing (.env.test).

To avoid manual sourcing of the environment files, e.g. for continuous development setups, you can pass the ENV=... before a call to make:

make ENV=test test-frontend

Note

You should always change the password of the admin account, especially for deployment. Only run the service in a secure environment to avoid leakage of the password information from the environment files.

Warning

If you make changes to these files, keep in mind that some parameters are written directly to the database and may need a reinitialization of the database (e.g., admin password) if changed there. The database therefore loses all data! To reinitialize the database, run make clean followed by make init.

Special Flags

The following flags are relevant to configure the functionality of the built CARE instance and should be adapted according to your needs.

Environment Variables

Flag

Meaning

NLP_USE

Set to true to connect the backend to the NLP Broker; we recommend false if you couple no NLP models.

LOGGING_ALLOW_FRONTEND

Set to true if log messages sent from a client frontend should be stored in the DB; we recommend true.

PUBLISH_DOC

Set to 1 if your local CARE documentation should be published on your server.

PUBLISH_API

Set to 1 if the documentation for the CARE API should be published on your server.

Note

After changes to the .env configuration files, you need to restart your server by running the build commands again.


Development Build

The development build consists of two individual components – the frontend and the backend – which can be build and run jointly or separately. For more advanced development, you need to understand the difference between the frontend and backend and how they interact. The frameworks used for each component, can be found in the Frameworks section. The source code is located in the frontend and backend folder, respectively.

Check out the following build options depending on your needs:

Basic

If you are not sure what kind of build you want and possibly make changes both in the frontend and the backend, just run the basic build using the following commands in different consoles and the given order:

make docker # starts the docker containers needed for development
make init   # initializes the database
make dev    # starts the development server (backend & frontend) - only linux!

This will start the development server for the backend as well as the frontend. This also starts up a database in a docker container and populates it with the necessary schemas.

Note

When starting the application for the first time, you need to initialize the database! Please make sure you run make init before and also after cleaning the environment with make clean!

Warning

The make dev command only works on Linux systems. On Windows, you need to start the frontend and backend separately with make dev-frontend and make dev-backend.

Frontend

Since the development of the frontend is not possible without starting the backend, the frontend development must always include the backend providing the database and the logic for data processing.

The frontend development allows hot-loading of the elements, meaning that elements are replaced without reloading or reinitializing the page when they are changed. Furthermore, the source code is not compressed, which allows debugging directly in the browser.

To start the frontend development, run the following command:

make dev-frontend

Anyway, it is possible to build the frontend in a minified code version without hot-loading:

make dev-build-frontend

For more information about the frontend development, see the section Frontend Development.

Tip

Another very helpful feature is the Vue Devtools browser plugin supporting extended debugging.

Backend

In contrast, it is possible to make the development in the backend independent from the frontend. However, it should be noted that many functions interact with each other, so often changes in the backend also involve the need to make changes in the frontend.

For a pure backend development, the frontend must first be built with:

make dev-build-frontend

After that, the backend can be started with:

make dev-backend

To shorten things, both commands can also be executed with make dev-build at once.


Deployment Build

If you want to deploy your current CARE code, please double-check the .env.main file to make sure it meets your needs. For a deployment build simply run the following command to create a docker container (name ends with _main), start it and detach it from your terminal.

make build   # creates docker container

Warning

For actual deployment, we heavily recommend running an NGINX in front of the actual backend. See Installation for instructions how to use it.

You can check the status and logs of the docker containers using the standard Docker CLI or Portainer. The container with the name ending in _server hosts the actual backend.


More Commands