Skip to content

Engineer onboarding

Welcome to the PetFolio onboarding guide. This documents will help you get your local development environment set up and ready to contribute.

Operating Systems

This onboarding documentation assumes that you are using a Windows device.

If you are using an alternative operating system the steps may differ, please update the documentation when appropriate to include alternative instructions.

Setup checklist

Git

Download and install Git for Windows. Once installed, Git will be available from the Command Prompt or PowerShell.

Use installation defaults

It's recommended that you select the defaults during installation unless there's good reason to change them

Try GitHub Desktop UI

If you're not a fan of using the command line, don't stress! Install GitHub Desktop for a handy GUI.

Configure line endings

Git on Windows will attempt to change all line endings to CRLF, for consistency we are opting to use LF line endings.

Configure Git line endings by running the following in a Command Prompt window: git config --global core.autocrlf input

Check the value of core.autocrlf by running git config core.autocrlf - it should be set to input.

Clone Repositories

The PetFolio system is comprised of two repositories, stored and managed in GitHub.

An Nx monorepo containing the UI applications and shared libraries.

1
2
git clone https://github.com/GraySolutions/petfolio-fe.git
cd petfolio-fe

A .NET solution containing the core API.

1
2
git clone https://github.com/GraySolutions/petfolio-service.git
cd petfolio-service

Bruno

Bruno is an open-source, fast and lightweight API client for exploring and testing APIs. It's designed to be a modern alternative to traditional API clients (like Postman) with a focus on speed, simplicity, and collaboration.

Install Bruno

Podman

Podman is an open-source container engine that serves as a free, open-source replacement for Docker.

Podman is daemonless, which means it doesn't need a background service running to manage containers. Unlike Docker, which uses a central daemon (dockerd) to run and control containers, Podman runs everything directly from the command line, only when you need it.

The following steps are required for Podman Desktop installation on a Windows machine.

Uninstall Docker

If you have previously setup Docker, you will need to uninstall it from your machine.

  • Install Podman Desktop for Windows
  • On Windows, running the Podman container engine requires running a Linux distribution on a virtual machine. To install WSL, open the Command Prompt and run: 
    1
2
    wsl --update
wsl --install --no-distribution

It is recommended that you restart your machine

  • Open the Podman Desktop application. The dashboard screen will likely display "Podman needs to be set up"
  • Click the "Set up" button and follow the guided setup.
  • Verify Podman is set up via the dashboard screen, the status within the Podman section should be "Running"

Configure Podman machine default connection

Podman may configure the podman-machine-default-root as your default machine.

We have encountered issues with this configuration, so recommended switching the default to podman-machine-default

In Command Prompt:

  • List Podman machine connections: podman system connection ls
  • Switch the machine default: podman system connection default podman-machine-default
  • Verify the new default machine: podman system connection ls

Configure rootless Podman machine connection

We have found the rootless Podman machine connection to be the most effective when working with our systems.

In Command Prompt:

  • Stop the machine: podman machine stop
  • Check rootful state of your machine: podman machine inspect
  • If "Rootful" is set to true, switch to rootless: podman machine set --rootful=false podman-machine-default
  • Verify rootful state is updated: podman machine inspect
  • "Rootful" should now be set to false
  • Start the machine: podman machine start

Node and npm

Node and npm are required for the petfolio-fe repository.

The repository pins the required Node and npm versions using Volta in the root package.json. Volta is a JavaScript tool manager that automatically switches to the correct Node and npm versions when you enter the project directory.

Install Volta

  1. Download and run the latest installer from the Volta releases page
  2. Follow the installation wizard, accepting the defaults
  3. Restart your terminal after installation

How Volta works

Volta installs itself into your PATH and intercepts calls to node and npm. When you run either command inside the petfolio-fe repository, Volta reads the pinned versions from package.json and uses them automatically. You do not need to run any activation commands.

Verify your setup

After installing Volta, open a new terminal in the root of the petfolio-fe repository and run:

1
2
3
4
5
node --version
# Expected: v24.x.x

npm --version
# Expected: v11.x.x

Volta downloads the pinned versions on first use, so the initial run may take a moment.

Volta pins both Node and npm

Unlike other version managers, Volta manages the npm version as well as Node. Both versions are declared in the volta field of package.json, so every developer and CI runner uses the same toolchain.

.NET SDKs

To run the petfolio-service backend you will need to install the appropriate .NET SDKs.

Our backend service currently uses .NET 9.0 - Download .NET 9.0

Entity Framework Core tools

The petfolio-service backend utilises Entity Framework Core. The command-line interface (CLI) tools for Entity Framework Core perform design-time development tasks.

For example, they create migrations, apply migrations, and generate code for a model based on an existing database.

  • To install, run dotnet tool install --global dotnet-ef
  • To verify installation, run dotnet ef

MySQL

For running the petfolio-service API locally, you'll need a local MySql server instance.

Integration tests do NOT require local MySQL

They use Testcontainers to automatically spin up a MySQL container via Podman. You only need MySQL installed if you want to run the API locally.

Installing MySQL for local API development

  1. Download MySql Installer
  2. Select "Full" setup type
  3. Run through download and installation steps
  4. Configure MySql Server
    • Set config type as "Development Computer"
    • Use recommended Authentication method
    • Set root password - don't forget this!
    • Add additional admin user (optional)
    • Use other recommended settings
  5. Configure MySql Router with recommended settings
  6. Within Petfolio.Service.Api, update appsettings.Development.json connection string: 
    1
2
3
4
5
    {
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Port=3306;Database=PetFolioDB;User={USERNAME};Password={PASSWORD};"
  }
}
    !!! tip "Default port" MySQL defaults to port 3306. Only change this if you configured a different port during installation.

Apply database migrations

After configuring your connection string, apply the EF Core migrations to create the database schema:

1
dotnet ef database update --project Petfolio.Service.Infrastructure --startup-project Petfolio.Service.Api
How do integration tests work without MySQL?

petfolio-service Integration tests use Testcontainers to automatically manage MySQL containers:

  • No manual database setup required
  • Each test run creates a fresh MySQL 8.0.35 container
  • Database is automatically cleaned between tests using custom SQL cleanup
  • Requires Podman (or Docker) to be running

To run tests: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Navigate to the repository
cd c:/code/petfolio-service

# Ensure Podman is running
podman machine start

# Run all tests (includes integration tests with containerized MySQL)
dotnet test

# Run only integration tests
dotnet test Tests/Petfolio.Service.IntegrationTests

Install dependencies

From the root of the petfolio-fe repository:

1
npm install

From the root of the petfolio-service repository:

1
2
dotnet restore
dotnet build

Run the apps

From the root of the petfolio-fe repository:

1
npx nx serve petfolio-business

The app will be available at http://localhost:4200.

From the root of the petfolio-service repository:

1
dotnet run --project Petfolio.Service.Api
Interface URL
API http://localhost:5213
Swagger https://localhost:7195/swagger