Setting up dev environment for FDE v3

Prerequisites

• Any Linux Distro
• Docker & Docker-Compose installed
• Node

---

Clone the repository

cd ~
git clone https://gitlab.vayu-software.de/fde/fde.git
cd fde

Before you setup the project first you need to setup few things

1. You need to create a docker network

docker network create proxy-network

2. You need .npmrc with your token from here

1. If there is no .npmrc on for host you should create it first in your home directory.

/home/your_username/.npmrc

2. Copy the content below and replace <your_token_here> with the actual value of your token.

//gitlab.vayu-software.de/api/v4/projects/89/packages/npm/:_authToken=<your_token_here>
//gitlab.vayu-software.de/api/v4/packages/npm/:_authToken=<your_token_here>
@vayu-fde:registry=https://gitlab.vayu-software.de/api/v4/projects/89/packages/npm

This is required for installing our private npm packages. Otherwise the setup will fail

Setup the project

./setup.sh

Start the project in development

npm run dev:start

Now using the Remote Explorer tab of VS Code open the /home/develop/fde folder

It will be now your project folder. It will help you to see only changes related to whole project.

If all docker containers have started properly, you should see the project is working at http://creator.localhost:1337 (the port will be random).

(You might need to forward the port 80. Here you can see how: https://github.com/microsoft/vscode-docs/blob/main/remote-release-notes/v1_54.md)

Later you can shut down all docker containers with the following command:

npm run dev:stop

Where to place the code in ./apps/creator

You can place the code in the following folders:

1. ./apps/creator/pages - only files containing next pages and ajax request handlers should be placed here

2. ./apps/creator/components - all react components that you want to create specifically for this project and all the files related to them should be placed here. Components, that could be used somewhere else, i.e. in a client application, should be transformed to or included in a separate npm package.

3. ./apps/creator/lib - here should be placed the code that could be used everywhere throughout the project

4. ./apps/creator/styles - common styling files should be placed here (mostly *.scss and *.module.scss files)

5. ./apps/creator/public - images, icons, manifest files and other files that should be used as is by the built project should be placed here.

Attention! Please, do not create any other folders directly inside creator folder. Use instead one of folders mentioned above.

Working with keycloak

When first setting up the project with ./setup.sh, keycloak imports a aready existing realm located in ./docker/config/keycloak/realms/import/keyclok-backup.json. The reason this realm exists is so you don't have to setup everything manually.

Import

If you want to get to the initial state of this realm or you want to import new realm:

1. First you need to place the realm file with file name keycloak-backup.json in ./docker/config/keycloak/realms/import/

2. After placing the realm into the correct directory, make sure that keycloak is running, and run this command

npm run keycloak:import

Export

If you want to export a realm(also can be used for backup):

1. First you need make sure that keycloak is running

2. The exported realm will be located in ./docker/config/realms/export/keycloak-backup.json by running

Any previous realm might get overwritten when using this command

npm run keycloak:export

Troubleshooting

Store Git credentials

To store your git credentials and not retype them on every git push or pull you can use this command

git config --global credential.helper 'store'

Port 80 is busy

It's likely because of standard apache server has taken it. To stop it and disable from launching in the future, run the following commands:

sudo service apache2 stop
sudo service apache2 disable

When opening http://creator.localhost:1337 I see error 502

Just wait a little bit. It takes time to start up the nodejs server of fde-creator project. If it took more then 1 minute, then check the logs of nodejs docker container.

When you have some problems with node_modules, they are located in the root directory of the project. The node_modules inside the creator are only mounted inside the docker container for development. We are using npm workspaces link here