Development - bcgov/PIMS GitHub Wiki
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.
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 selectSystem
. - Scroll down to find and click
Advanced system settings
. - Click on
Environment Variables...
button, then clickNew...
button. - Add a new variable with the name
FORCE_COLOR
and the valuetrue
, save your changes and restart bash.
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
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
- 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.
- 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.
- 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
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
- from someone on the development team,
- or from https://citz-imb.atlassian.net/l/cp/p86LrnB8
- if you don't have access to this confluence doc you can request permission from the IMB Full Stack Developer Chapter Lead.
for the file ./backend/api/.env
.
# Add these to ./backend/api/.env
Keycloak__Secret=
Keycloak__ServiceAccount__Secret=
Keycloak__FrontendClientId=
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.
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.
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.
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.
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 |