Skip to content

Engineer Onboarding

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

Note

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

Git

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

Tip

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

Tip

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

Important

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

Configure Git line endings, run 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.

.NET SDKs

To run this service you will need to install the appropriate .NET SDKs.

This service currently uses .NET 9.0 - Download .NET 9.0

Volta

With Volta, you can select a Node engine once and then stop worrying about it. You can switch between projects and stop having to manually switch between Nodes.

Install the latest Volta package.

Install node and npm

Within a Command Prompt window, run volta install node to install the latest LTS version.

Entity Framework Core tools

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

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.

Warning

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

Tip

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

Note

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

Important

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

MySql

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

Note

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
  5. Set config type as "Development Computer"
  6. Use recommended Authentication method
  7. Set root password - don't forget this!
  8. Add additional admin user (optional)
  9. Use other recommended settings
  10. Configure MySql Router with recommended settings
  11. Within Petfolio.Service.Api, update appsettings.Development.json connection string: 
    1
2
3
4
5
6
    {
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Port={PORT};Database=PetFolioDB;User={USERNAME};Password={PASSWORD};"
  },
  // Everything else...
}

Running Tests Without MySQL

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
# 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

Performance:

  • Comprehensive test suite with fast execution
  • Integration tests with real database using Testcontainers
  • Shared container pattern ensures fast test execution