Development

Development

Development is currently supported through the use of Docker containers, and or local development with VS Code and Visual Studio 2019. Although any IDE that supports the languages should work.

Computer Setup

Install the following applications.

• VS Code
• Docker Desktop
• Git
• .NET Core SDK or version 5 (they are backward compatible)
• EF CLI (skip dotnet add package ..., this is already completed)

Windows

• GitBash (recommended to use git bash when running make commands).
• chocolately.
• make with command choco install make --version=3.81. Tutorial Here for installing make and updating your PATH.

MacOS

• Homebrew
• coreutils with command brew install coreutils.

Initial Setup

1. Create a fork of the repository https:/bcgov/pims.

2. Clone the forked branch you want work on. If using Docker, ensure you are using a local (not network) drive.

   git clone https:/[username]/bcgov/pims

3. Generate the .env files required to run the solution. You will be prompted for usernames, pick ones of your choosing. After generating the files, you may edit the randomly generated password (it's used in multiple .env files).

   ./scripts/gen-env-files.sh

4. Configure Docker Desktop

   • General > "Use WSL 2 based engine": needs to be unchecked
   • Resources > File Sharing: add /path/to/PIMS, click "Apply & Restart"

5. Configure Keycloak. This requires logging into Keycloak and updating your .env files with the correct client secret.

   docker-compose up -d keycloak

   Login to the Keycloak Administration Console with your username and password (found in /auth/keycloak/.env). It can take a moment for it to connect, it may not load right away.

   http://localhost:8080

   In Keycloak: Configure > Clients > pims-service-account, copy Credentials > Secret and update all your .env files with the client secret.

   /backend/api/.env - Keycloak__ServiceAccount__Secret={client secret}

   /tools/keycloak/sync/.env - Auth__Keycloak__Secret={client secret}

   /tools/import/.env - Auth__Keycloak__Secret={client secret}

6. Setup your local development container environment. This will require installing .NET Core CLI and the .NET Core EF CLI.

   Seed Data You will need to request a JSON file that contains properties for the import to work.

   make setup

   Or if you want to do this manually.

   docker-compose build --no-cache
   docker-compose up -d
   cd ./backend/dal
   dotnet ef database update
   cd ../../tools/keycloak/sync
   dotnet run
   cd ../../import
   dotnet run
   cd ../../

7. Once running you can now start using the solution - http://localhost:3000

   For git developer workflow instructions, see GitHub Workflow.

Make Scripts

To simplify development once the initial setup is complete, you can use the make commands.

make help

Command	Description
setup	Setup local container environment, initialize keycloak and database
build	Builds the local containers
up	Runs the local containers
stop	Stops the local containers
down	Stops the local containers and removes them
restart	Restart local docker environment
refresh	Recreates local docker environment
clean	Removes local containers, images, volumes, etc
npm-clean	Removes local containers, images, volumes for frontend
npm-refresh	Cleans and rebuilds the frontend to handle npm changes
db-migrations	Display a list of the database migrations
db-add	Create and add a new database migration (n={migration})
db-update	Update the database with the latest migration
db-rollback	Rollback the specified database migration (n={migration})
db-remove	Remove the last database migration files
db-clean	Re-creates an empty docker database - ready for seeding
db-refresh	Refreshes the docker database
db-drop	Drop the database
db-seed	Imports a JSON file of properties into PIMS
keycloak-sync	Syncs accounts with Keycloak and PIMS
server-run	Starts local server containers
client-test	Runs the client tests in a container
server-test	Runs the server tests in a container
convert	Convert Excel files to JSON