Skip to content

Setup Development Environment

Jump to bottom
joschne edited this page Jun 6, 2024 · 11 revisions

Goal

  • toolbox is running on your computer
  • you can set breakpoints on client and server
  • you understand how a request from client is going to server and db and back

Installation

Windows users: You might consider to use WSL maybe together with the VSCode extension

Install node

Install a node version manager

We recommend using a version manager as versions change very quickly. You will likely need to switch between multiple Node.js versions based on the needs of different projects you're working on. Node Version Manager, more commonly called nvm, is the most popular way to install multiple versions of Node.js.

For Windows in english, in french

For Mac/Linux in english

Install node.js versions

Install the node versions needed by toolbox server and client.

Find the required node versions for toolbox server and client in {"engines": {"node": ... }}.

Then install the two required versions, at time of writing 12.8.1 for server and 18 for client:

nvm install 12.8.1
nvm install 18

This installs node and npm. The npm version is bound to node version, as documented here.

Install docker

For running the postgres database, needed to develop and test the toolbox, we recommend using docker.

Install docker on your machine.

Install Visual Studio Code

We recommend to use VSCode as an IDE. This is not mandatory, but it can be useful:

  • to share editor settings and extensions, e.g. for automatic code formatting.
  • to share launch scripts, e.g. to compile and start the webserver

Download

Hint: For IntellJ users, there is an IntellJ IDEA Keybindings Extension for VSCode.

Start the services

Setup dev-stack

The dev-stack provides a docker compose configuration to start all you need to launch and develop the toolbox. (This is very helpful to deal with the complex setup with Kafka. If Kafka is dropped, the dev-stack can be simplified or dropped.)

Get the code:

git clone https://github.com/geovistory/dev-stack.git

Start the dev stack containers:

cd dev-stack
bash scripts/up

Find more documentation here: https://github.com/geovistory/dev-stack

If the stack is too heavy, choose a lightweight stack by choosing another DOCKER_COMPOSE_FILE in your .env file.

Make sure, the postgres database is running (by default on port 1110).

Setup toolbox for development

Get the code:

git clone https://github.com/geovistory/toolbox.git

From the root folder of toolbox, checkout restore-functionality (until it is merged):

git checkout restore-functionality

TODO: Remove the above lines after branch is merged

Start server

From root of the repo, call this to open the server folder in VSCode:

code server

In the toolbox/server folder, install node modules (e.g. using the terminal of VSCode):

nvm use 12.8.1 # pick the version from server/package.json

npm install # or just npm i

This will add a node_modules folder with all dependencies.

Create the .env by copying .env.example:

cp .env.example .env

This contains all important environment variables, as e.g. the database connection string.

Modify CLIENT_URL and SERVER_URL to match the ports as exposed by default in development mode:

CLIENT_URL=http://localhost:4200
SERVER_URL=http://localhost:3000

Check that GV_DB_REVIEW_COPY is correctly pointing to the postgres instance launched by dev-stack

GV_DB_REVIEW_COPY="postgres://postgres:local_pw@localhost:1110/toolbox_db"

Set the email configurations so that you can later register your account:

# address used to send emails from
GEOV_EMAIL_ADDRESS=

# host name of smtp server
GEOV_EMAIL_HOST=

# port of smtp server
GEOV_EMAIL_PORT=

# passwort of smtp account
GEOV_EMAIL_PASSWORD=

Start the server by hitting F5 or by clicking on "Launch Webserver":

image

This starts a process defined in .vscode/launch.json that compiles typescript and starts the start script.

In the terminal you will be asked, to choose the environment variable to read the database-connection string from. Choose GV_DB_REVIEW_COPY as it should point to the database toolbox_db created by dev-stack (on port 1110) in your .env file.

The server starts and listens on port 3000.

Serve client

Open the client folder in VSCode:

code toolbox/client

Install node modules using the terminal of VSCode (in toolbox/client)

nvm use 18 # pick the version from client/package.json

npm install # or just npm i

This will add a node_modules folder with all dependencies.

Create the .env by copying .env.example:

cp .env.example .env

This contains all important environment variables.

# URL of toolbox server api
API_URL=http://localhost:3000

# URL of server hosting angular assets
ASSETS_URL=http://localhost:4200

Set API_URL to port 3000 in order to connect to the server running in debug mode (started above). (Port 1130 is the default port of toolbox server in dev-stack.)

Set ASSETS_URL to 4200 to connect to the angular server when running in development mode:

Start client in development mode

npx nx serve app-toolbox

This starts a process that watches the client/src files, compiles typescript and serves the application, be default on port 4200.

Inspect Toolbox

Register

Open http://localhost:4200.

Register with a new account. When registered login and view your projects.

Set breakpoint on server

In the VSCode window running the server, set a breakpoint on line 48 in:

src/controllers/account-data/account-data.controller.ts

Reload http://localhost:4200/projects and see the breakpoint has been hit.

Add your user to existing projects

In order to see existing projects in the project list, add your account to the existing projects:

INSERT INTO account_project_rel (account_id, fk_project, role)
SELECT acc.id, proj.pk_entity, 'owner'
FROM projects.project proj,
     account acc
WHERE acc.email = 'email-used-for-registration'

Add admin role to your account

In order to access the admin interface of the toolbox, you need to map your account to the admin role (id 1):

INSERT INTO rolemapping (principaltype, principalid, roleid)
SELECT 'USER', acc.id, 1
FROM account acc
WHERE acc.email = 'email-used-for-registration';

Now you should be able to access /admin in the toolbox UI.

Clone this wiki locally