04_Development Setup

Running the application

First, install the necessary packages in both the backend and the frontend folders (note that we use Yarn as our package manager instead of NPM):

yarn

To locally run a project built with Flox, the following commands are available (all needed commands are also located in the related package.json):

• Running frontend locally (any of these) within /frontend. All valid commands are also specified in frontend/package.json:

yarn dev         // running with client-side rendering
yarn dev:pwa     // running as progressive web application
yarn dev:ssr     // running with server-side rendering

• Runnning backend + database locally using Docker within /backend. All valid commands are also specified in backend/package.json:

docker-compose up -V --build

or just:

yarn docker:dev

This will create one container each for backend, database and (optionally) NocoDB. Note: you must have Docker Desktop installed and running for this command to work. If you are running on a Windows machine, you may need to enable CPU virtualization in BIOS/UEFI.

Database

Direct Access

The database uses PostgreSQL and is accessed directly from the backend using TypeORM.

For development purposes, the locally running database can also be accessed through WebStorm's database plugin. Install it by searching for "Plugins" within WebStorm's preferences, then searching for "Database":

After installing the plugin, you will be shown a new tool called "Database" on the right-hand side of Webstorm. Open it, click "+" -> "Data Source" -> "PostgreSQL":

Then, enter the database name (Database), username, and password according to the values specified in the application's .env file. These parameters are called DB_DATABASE, DB_USER and DB_PASSWORD in the .env file, respectively.

NocoDB

As an additional tool, NocoDB can be used to directly perform operations and look at data on the database. Setting up a NocoDB container is an optional part of the docker-compose file for running backend/database. By default, NocoDB runs on localhost:8080. To use it, you will initially need to create an account as well as set up your project ("Create new project using an existing database"). Choose "Postgres" as the database type, and enter your database's details, as shown below:

Note that the IP adress you have to use may be different. Due to the way networking works between Docker containers, using localhost will NOT work. To find your database container's IP, run the following command in your terminal of choice:

docker inspect database

Look for a field named IPAddress, and use that value. You're now ready to start adding and inspecting data on your database using NocoDB!

Creating a User

If you use flox for the first time, you can sign in like a regular user using the Signup page on localhost. This will create a new Cognito identity for you that you can use from know on while developing on this project. After you have signed up, you'll receive an E-Mail from cognito that contains a code, which you need to enter during the first login progress. Also, you need to have an authenticator app like Google Authenticator, to setup 2FA.

Login with user

Note that when you restart your backend docker container, you can no longer login. A message appears that the account was not found. However, you can also not signup again, because that same E-Mail is already registered on Cognitio and can not be reused. You need to insert your data manually into the database again. If you have setup the database connection within webstorm as instructed previously, navigate to the following table: app_db > public > tables > users. Double-Click the user-table and insert a new entry. Leave the uuid empty as it will be generated by PostgreSQL. Click on the createAt date and insert the current time. Leave updatedAt and deletedAt empty. As your username and email, enter your email address that you used during signup. To get your cognitoUuid, navigate to AWS, search for "Cognito". Make sure you are in the Frankfurt region. Under "Userpools", select the appropriate project, then scroll down to "Users" and clock on the user that corresponds to your email. Copy the users User-ID (Sub) and add it to your database field cognitoUuid. Finally, set your role to ADMIN. The whole insert statement should look as follows:

Lastly, click on the green Arrow-Up to submit your changes. You can now use that user to login to your project. Note that if you find the previous instructions too verbose to repeat again after every backend restart, you can copy-paste the following SQL Query and run it in the PostgreSQL Console.

INSERT INTO public."user" (uuid, "createdAt", "updatedAt", "deletedAt", username, email, "cognitoUuid", role)
VALUES (DEFAULT, '2022-10-01 12:00:00.000000'::timestamp, DEFAULT, null::timestamp, 'FIRSTNAME.LASTNAME@polygon-software.ch'::varchar,
        'FIRSTNAME.LASTNAME@polygon-software.ch'::varchar, 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'::varchar, 'ADMIN'::varchar);

Be sure to replace the string values with your appropriate ones.