Skip to content

Development

Jump to bottom
TaylorFries edited this page Feb 13, 2024 · 47 revisions

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.

1) Install Git

If you don't already have Git installed, install it now.
Git - Make sure option for Git Bash is selected if on Windows.

(For Windows 10) Follow the instructions below to ensure console colors work correctly:

  • Right click on Windows icon in bottom-left of screen and select System.
  • Scroll down to find and click Advanced system settings.
  • Click on Environment Variables... button, then click New... button.
  • Add a new variable with the name FORCE_COLOR and the value true, save your changes and restart bash.

2) Clone

Clone the repository from https://github.com/bcgov/PIMS. Run the following command in Git Bash (recommended for Windows) or Command Line. If using Docker, ensure you are using a local (not network) drive.

# URL found on Code tab of repository under the green code button.
git clone https://github.com/bcgov/PIMS.git

Change into the pims directory cd pims

3) Install Applications

Install the following applications

  • VS Code
  • Docker Desktop - If installing for the first time, unselect WSL 2 option in the installer.
  • .NET Core SDK
    • Install SDK 6.0.408 (as of April 14, 2023), which includes the ASP.NET Core Runtime 6.0.16, and .NET Runtime 6.0.16
  • EF CLI - Skip the step that says to run dotnet add package Microsoft.EntityFrameworkCore.Design

Windows Only

  • Chocolatey - Read installation instructions under "Install with PowerShell.exe" Run PowerShell as Administrator.
  • Install make with command
choco install make --version=4.3

Here is the Make Installation Instructions for reference. You need to update your PATH for make. The documentation is out of date and only has instructions for Windows 7.

Update PATH for make in Windows 10

  • Use Windows search bar and search for “Edit system environment variables”.
  • Click on the “Environment variables” button.
  • Select “Path” from the list under “System variables”.
  • Click “Edit”, then “New”.
  • Paste the following
C:\ProgramData\chocolatey\lib\make\bin
  • Save and close tabs.

MacOS Only

  • Homebrew
  • Install coreutils with command
brew install coreutils

4) Install dotnet-ef (Since we've upgraded to .NET version 7, we should install at least dotnet-ef version 7.0.7)

Install dotnet-ef

dotnet tool install --global dotnet-ef --version 7.0.7

or the following command will install the latest version of dotnet-ef (As of June, 2023 it is version 7.0.7)

dotnet tool install --global dotnet-ef

5) Generate Environment Files

Generate the env files with the following command. You will be prompted for multiple usernames. Do Not set this as "admin", your first name is a good choice.
After generating the files, you may edit the randomly generated password (it's used in multiple .env files).

./scripts/gen-env-files.sh

You will need to obtain 3 variables either

for the file ./backend/api/.env.

# Add these to ./backend/api/.env
Keycloak__Secret=
Keycloak__ServiceAccount__Secret=
Keycloak__FrontendClientId=

6) Configure Docker

Configure Docker Desktop
- General > "Use WSL 2 based engine": needs to be unchecked.
- Resources > Advanced: ensure memory is 6 GB or greater.
- Resources > File Sharing: add path to PIMS. Ex: c:\pims.
- Click "Apply & Restart".

If you have issues trying to unselect WSL 2, you may have to uninstall Docker Desktop, reinstall it and unselect the WSL 2 option in the installer.

7) Seed Database Data

Seed Data - You will need to request a ZIP file (mssql-data.zip) from someone on the development team. Once you have obtained this file, place the unzipped contents inside ./database/mssql/data/.

. 
├── database
|   └── mssql 
|       └── data // Place unzipped files here.

8) Setup Application

Use make to set up the containers. If you run into this error: "failed size validation: 121295976 != 141401206: failed precondition" while running either the make setup or restart commands, you may need to turn off your vpn.

make setup

This should output a summary before finishing. If it hangs for too long and won't finish, re-try the command.


9) Final Step

Restart the application

make restart

If the app crashes, try the command again.
It will take the app a few minutes to load. The app container console will display when the server has started.
Open Application in Browser (localhost:3000)
If the app is stuck on the loading animation, refresh the page.

Login with your idir account.

If everything is working correctly, you should see colourful blips on the map that represent properties.

If you do not see anything on the map and get the following error message, the data did not get seeded or can not be retrieved. You may have missed a step, not allocated enough memory in Docker settings, or placed the zip file data in the incorrect directory. The first thing you should try is stopping the containers with make down, then make setup, then make restart.

- Request failed with status code 500: An error occured while fetching properties in inventory.

To stop the application, run make stop.
To restart the application, run make restart.
To start the application, run make start.

For git developer workflow instructions, see Git 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
up-dev Runs the local containers, but uses the frontend-dev container.
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-dev
npm-refresh Cleans and rebuilds the frontend-dev container and cache 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
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
Clone this wiki locally