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

Make Commands
Command	Purpose
`make doc`	Compile the documentation (AsyncAPI and Sphinx documentation).
`make doc_asyncapi`	Compile the AsyncAPI documentation.
`make doc_sphinx`	Compile the Sphinx documentation (this documentation).
`make init`	Initialize the database (creating tables from backend migrations)
`make test`	Running the backend api tests.
`make backup_db CONTAINER=<name>`	Creates a database dump from the given postgres container and stores it in the db_dumps folder.
`make recover_db CONTAINER=<name> DUMP=<path>`	Loads a given database dump from <path> into the postgres container <name>.
`make clean`	Cleans the environment by removing all docker containers and images, files and folders.
`make kill`	Kills all node processes. (only unix)
`make lint`	Runs the linter for the frontend.