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: * `Node.js `_ (includes npm) .. warning:: CARE requires **Node.js version >= v23** for the development environment to work correctly. Older versions (e.g., v12.x on WSL) will cause runtime errors or build failures. You can check your currently installed versions by running: .. code-block:: bash node -v npm -v * `Docker `_ * `Docker Compose `_ * `GNU Make `_ .. 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: .. code-block:: bash 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: .. code-block:: bash 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. .. list-table:: Environment Variables :widths: 25 75 :header-rows: 1 * - 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 :doc:`Frameworks <../for_developers/basics/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: .. code-block:: bash 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: .. code-block:: bash make dev-frontend Anyway, it is possible to build the frontend in a minified code version without hot-loading: .. code-block:: bash make dev-build-frontend For more information about the frontend development, see the section :doc:`Frontend Development <../for_developers/frontend/frontend>`. .. 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: .. code-block:: bash make dev-build-frontend After that, the backend can be started with: .. code-block:: bash 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. .. code-block:: bash make build # creates docker container .. warning:: For actual deployment, we heavily recommend running an `NGINX `_ in front of the actual backend. See :doc:`../getting_started/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 ------------- .. list-table:: Make Commands :widths: 60 40 :header-rows: 1 * - Command - Purpose * - ``make help`` - Show all available make targets. * - ``make doc`` - Build the Sphinx documentation (default doc target). * - ``make doc_sphinx`` - Build the Sphinx documentation inside the docs container. * - ``make doc_clean`` - Clean the Sphinx documentation. * - ``make dev`` - Run frontend (dev) and backend (dev) together. (Unix only) * - ``make dev-backend`` - Run backend in development mode. * - ``make dev-frontend`` - Run frontend in development mode. * - ``make dev-build`` - Build frontend in dev mode and run backend in dev mode. * - ``make dev-build-frontend`` - Build frontend in development mode only. * - ``make build`` - Create a dockerized production build (frontend, backend, nlp, services). * - ``make build-frontend`` - Build frontend in production mode. * - ``make build-clean`` - Clean production build (containers, networks, volumes). * - ``make docker`` - Start development docker containers (postgres, rpc services). * - ``make rpc_moodle_build`` - Build and start the Moodle RPC container (dev setup). * - ``make db`` - Initialize (migrate) the database. * - ``make init`` - Initialize the database and install npm packages in all utils/modules subdirectories. * - ``make backup_db CONTAINER=`` - Create a database dump from the given Postgres container into ``db_dumps/``. * - ``make recover_db CONTAINER= DUMP=`` - Load a given database dump into the specified Postgres container. * - ``make test`` - Run backend unit tests. * - ``make test-rpc`` - Run backend RPC tests. * - ``make test-modules`` - Run unit tests for the ``editor-delta-conversion`` module. * - ``make lint`` - Run frontend linter. * - ``make modules`` - Install npm packages in all ``utils/modules`` subdirectories. * - ``make clean`` - Remove ``node_modules``, ``dist``, docker containers/networks, and reset the DB state. * - ``make kill`` - Kill all Node.js processes (Unix only).