Building¶
This document summarises the build and release process for the Ocelot project. The build scripts are written using Cake (C# Make), with relevant build tasks defined in the ‘build.cake’ file located in the root of the Ocelot project. The scripts are designed to be run by developers locally in a Bash terminal (on any OS), in Command Prompt (CMD) or PowerShell consoles (on Windows OS), or by a CI/CD server (currently GitHub Actions), with minimal logic defined in the build server itself.
The final goal of the build process is to create Ocelot.*
NuGet packages (.nupkg files) for redistribution via the NuGet repository or manually.
The build process consists of several steps: (1) compilation, (2) testing, (3) creating and publishing NuGet packages, and (4) making an official GitHub release.
The build process requires pre-installed .NET SDKs on the build machine (host) for all target framework monikers: TFMs are net8.0
and net9.0
currently.
In general, the build process is the same across all environments and tools, with a few differences described below.
In IDE¶
In an IDE, a DevOps engineer can build the project in Visual Studio IDE or another IDE in Release configuration mode, but the latest .NET 8/9 SDKs must be pre-installed on the local machine. However, this approach is not practical because the generated ‘.nupkg’ files must be uploaded to NuGet manually, and the GitHub release must also be created manually. A better approach is to utilize the ‘build.cake’ script In terminal, which covers all building scenarios.
In terminal¶
Folder: ./
These are local machine or remote server building scenarios using build scripts, aka ‘build.cake’. In these scenarios, the following two commands should be run in a terminal from the project’s root folder:
dotnet tool restore && dotnet cake # In Bash terminal
dotnet tool restore; dotnet cake # In PowerShell terminal
Note: The default target task (“Default”) is “Build”, and output files will be stored in the
./artifacts
directory.
To run a desired target task, you need to specify its name:
dotnet tool restore && dotnet cake --target=name # In Bash terminal
dotnet tool restore; dotnet cake --target=name # In PowerShell terminal
For example,
dotnet cake --target=Build
It runs a local build, performing compilation and testing only.
dotnet cake --target=Version
It checks the next version to be tagged in the Git repository during the next release, without performing compilation or testing tasks.
dotnet cake --target=CreateReleaseNotes
It generates Release Notes artifacts in the
/artifacts/Packages
folder using theReleaseNotes.md
template file.dotnet cake --target=Release
It creates a release, consisting of the following steps: compilation, testing, generating release notes, creating .nupkg files, publishing NuGet packages, and finally, making a GitHub release.
Note 1: The building tools for the
dotnet tool restore
command are configured in the dotnet-tools.json file.Note 2: Some targets (build tasks) require appropriate environment variables to be defined directly in the terminal session (aka secret tokens).
With Docker¶
Folder: ./docker
The best way to replicate the CI/CD process and build Ocelot locally is by using the Dockerfile.build file, which can be found in the ‘docker’ folder in the Ocelot root directory. For example, use the following command:
docker build --platform linux/amd64 -f ./docker/Dockerfile.build .
You may need to adjust the platform flag depending on your system.
Note: This approach is somewhat excessive, but it will work if you are a masterful Docker user. 🙂 The Ocelot team has not followed this approach since version 24.0, favoring With CI/CD-based builds and occasionally building In terminal instead.
With CI/CD¶
The Ocelot project utilizes GitHub Actions as a CI/CD provider, offering seamless integrations with the GitHub ecosystem and APIs.
Starting from version 24.0, all pull requests, development commits, and releases are built using GitHub Actions workflows.
There are three workflows: one for pull requests (PR), one for the develop
branch (Develop), and one for the main
branch (Release).
Note: Each workflow has a dedicated status badge in the Ocelot README: the
button and the
button, with the PR status being published directly in a pull request under the “Checks” tab.
The PR workflow will track code coverage using Coveralls.
After opening a pull request or submitting a new commit to a pull request, Coveralls will publish a short message with the current code coverage once the top commit is built.
Considering that Coveralls retains the entire history but does not fail the build if coverage falls below the threshold, all workflows have a built-in 80% threshold,
applied internally within the build-cake
job, particularly during the “Cake Build” step-action.
If the code coverage of a newly opened pull request drops below the 80% threshold, the ‘build-cake’ job will fail, logging an appropriate message in the “Cake Build” step.
Note 1: There are special code coverage badges in Ocelot README: the Develop
button and the Release
button.
Note 2: The current code coverage of the Ocelot project is around 85-86%. The coverage threshold is subject to change in upcoming releases. All Coveralls builds can be viewed by navigating to the ThreeMammals/Ocelot project on Coveralls.io.
Documentation¶
Folder: ./docsDashboard: Ocelot app project
Documentation building is configured using the ‘.readthedocs.yaml’ integration file, which allows builds to run separately via the Read the Docs publisher. All build artifacts and document sources are located in the ‘docs’ folder. More details on the documentation build process can be found in the README.
Note 1: Documentation builds have a dedicated status badges in Ocelot README: the Develop
button and the Release
button.
Note: Documentation can be easily built locally in a terminal from the ‘docs’ folder by running the
make.sh
ormake.bat
scripts. The resulting documentation build files will be located in the./docs/_build
folder, with the HTML documentation specifically written to the./docs/_build/html
folder.
Testing¶
The tests should run and function correctly as part of the building process using the dotnet test
command.
You can also run them in Visual Studio IDE within the Test Explorer window.
Depending on your build scenario, Ocelot testing can be performed as follows.
In IDE: Simply run tests via the Test Explorer window of Visual Studio IDE.
In terminal: There are two main approaches:
Run the
dotnet test
command to perform all tests (unit, integration, and acceptance):dotnet test -f net8.0 ./Ocelot.sln
Or run tests separately per project:
dotnet test -f net8.0 ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj # Unit tests only dotnet test -f net8.0 ./test/Ocelot.IntegrationTests/Ocelot.IntegrationTests.csproj # Integration tests only dotnet test -f net8.0 ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj # Acceptance tests only
Run
dotnet cake
command:dotnet cake --target=Tests
to perform all tests (unit, integration and acceptance). Or run tests separately per testing project:dotnet cake --target=UnitTests # unit tests only dotnet cake --target=IntegrationTests # integration tests only dotnet cake --target=AcceptanceTests # acceptance tests only
With Docker: This approach is not recommended. Instead, perform automated testing With CI/CD or opt for In terminal-based testing, which is a more advanced method.
With CI/CD: In GitHub Actions workflows, the testing process consists of separate testing steps, organized per job:
In the ‘build’ job: There are ‘Unit Tests’, ‘Integration Tests’, and ‘Acceptance Tests’ steps.
In the ‘build-cake’ job: There is a ‘Cake Build’ step responsible for performing tests internally.
SSL certificate¶
To create a certificate for Testing, you can use OpenSSL:
Install the openssl package (if you are using Windows, download the binaries here).
Generate a private key:
openssl genrsa 2048 > private.pem
Generate a self-signed certificate:
openssl req -x509 -days 1000 -new -key private.pem -out public.pem
If needed, create a PFX file:
openssl pkcs12 -export -in public.pem -inkey private.pem -out mycert.pfx