Development
Prerequisites:
-
NodeJS - Version should match the version used in the Docker images
- Node Version Manager is the recommended way of managing multiple Node versions.
- Docker Desktop
- Visual Studio Code or another suitable IDE.
On your local machine, run this command in your terminal/console:
git clone https://github.com/bcgov/PIMS.git
Create a .env file in the root directory and populate it using the definitions in the Express API README. There is a .env-template file in the root directory that you can use as a starting point.
Some values are specific to your local environment, but many will have to be obtained from external services, such as SSO Keycloak, CHES, LTSA, and BC Geocoder.
The Vault instance for the DEV environment will have acceptable values for local development in most cases.
Please reach out to another developer to help with this initial setup if needed.
PIMS uses PostgreSQL for local development. Ensure the ENV entries for PostgreSQL are populated first.
Start the PostgreSQL container using docker-compose up --build -d postgres
Check Docker Desktop or use the Docker CLI to ensure the container is running.
Navigate to /express-api in your terminal.
Run npm i to install the necessary dependencies.
Run npm run dev to start the API service.
At this point, the database migrations run. The initial migrations also contain the seed data that will allow you to use PIMS.
Option 1:
The database will require a single Agency to be manually inserted. You can connect to your database with one of the following tools, although there are many more:
- SQL Tools (VS Code Extension)
- PostgreSQL (VS Code Extension)
- Azure Data Studio
Run this query against your database to insert a test agency:
INSERT INTO agency (
created_by_id,
name,
code,
send_email
)
VALUES (
'00000000-0000-0000-0000-000000000000',
'Test Agency',
'TAG',
FALSE
);Option 2:
A secondary option to this method of database seeding is to clear the database schema and restore from an existing backup of one of the live environments. In Microsoft Teams, there is a PIMS team. The Internal Team channel contains a postgres_dump file that can be used for this purpose, although the channel will require an access request.
To do this, copy the postgres_dump file into your /database/postgres/data/db directory.
Ensure the public schema has been cleared by running:
DROP SCHEMA public CASCADE;
CREATE SCHEMA public;You will likely have to rebuild the database continer at this step so that the volume mounts correctly. See step 3 above on how to run the database container.
Then run this command from within the postgres container:
psql -U postgres --single-transaction --set ON_ERROR_STOP=1 postgres < <path_to_file>postgres_dump
eg. if your postgres_dump file is in the container under data/db you will run the following:
psql -U postgres --single-transaction --set ON_ERROR_STOP=1 postgres < ./data/db/postgres_dump
This assumes your container's database is called postgres and has a postgres user.
The database should now be populated with production-similar data.
This second option is more effort, but it will provide a much more complete set of data to experiment with in PIMS.
Navigate to /react-app in a new terminal.
Run npm i to install the necessary dependencies.
Run npm run dev to start the frontend service.
You should see something similar to this in your terminal:
In your browser, navigate to the Local address to view the app.
Normally, a new user submits and access request and an administrator will grant them a role and Active status. Without this, a user cannot see the application past the home page and access request pages.
Because there is no administrator for your local, you will have to edit your user entry manually.
Submit your access request using the application, then query the user table for your entry.
SELECT * from "user";Once you have identified your entry, copy the value from the username column and update your record like so:
UPDATE "user"
SET status = 'Active', role_id = '00000000-0000-0000-0000-000000000000'
WHERE username = '<username goes here>';That's it! You're ready to begin development and contribute to PIMS.
In addition to the database, the frontend and API containers can also be run locally with the command:
docker-compose up --build -d pims-api-v2 pims-app-v2
These are not development containers, so changes made to files will not be reflected in these containers until they are rebuilt. We recommend that developers build these containers to test their changes but use the npm run dev commands for initial work.
Make all changes in a separate branch on your local. Developers are restricted from committing or merging into the main branch without a Pull Request (PR).
PR titles should follow the format of PIMS-#### My PR Title, where the title is something summarizing the ticket or changes.
New PRs should include this information:
- the ticket number and a link to that ticket
- the changes made at a high level
- testing instructions for other developers
- any known issues related to these changes
- confirmation via the checkbox that you have met the requirements listed in the PR template
When ready, publish your branch and open a PR in the Draft status.
At this point, GitHub Actions will run the necessary workflows that will look for linting issues, check test coverage, and build temporary images with your changes.
If all the actions pass successfully, release your PR for review.
Developers listed in the CODEOWNERS file (.github/CODEOWNERS) will be added as reviewers automatically. At least one reviewer is needed to approve the PR before it can be merged.
Once the review is complete, the PR is free to be merged.
There are a number of tools, technologies, and services used in PIMS. It's not necessary to be familiar with all of them to be involved, but we have compiled a list of them here to assist with developer onboarding.
These terms are only related to the technology side of PIMS. For terms related to the business logic, see the Glossary page.
- Docker
- Git
- GitHub
- GitHub Actions
- OpenShift
- SQL Tools (or similar tool)
- Visual Studio Code