A basic template for a Doppler microservice based on .NET with CI, CD, Code Formatting, Authentication, and other common practices in Doppler teams.
For the moment, it is only a kind of example. In the future, it could be converted into a Yeoman or dotnet new scaffolding template 🤷♂️.
We base our CI/CD process on Jenkins, Docker Hub, and Docker Swarm.
Jenkins generates the images based on doppler-jenkins-ci.groovy (a renamed Jenkisfile). We refer to these generated images in a Docker Swarm using an auto-redeploy approach. The Doppler Swarm repository stores the configuration of our Docker Swarm.
You can find a detailed description of our Git flow and the relation with Docker Hub in Doppler-Forms repository, but basically, it is the following:
-
Pull Requests generates images with tags like
pr-177
(pr-{pull request id}
) and (pr-{pull request id}-{commit id}
). -
Merging in
main
(ormaster
in some repositories) generates images with tags likemain
andmain-60737d6
(main-{commit id}
). In general, these images are deployed automatically into the QA environment. -
Resetting the branch
INT
generates images with tags likeINT
andINT-60737d6
(INT-{commit id}
). In general, these images are deployed automatically into the INT environment. -
Tagging with the format
v#.#.#
generates images with tags likev1
,v1.3
,v1.3.0
,v1.3.0_982c388
. In general, our Production environment refers to images with tags likev1
(only the mayor), so, depends on that, these images could be deployed automatically to the Production environment.
The source of truth related to the build process is doppler-jenkins-ci.groovy (a renamed Jenkisfile). It basically runs docker build, so, you can reproduce jenkins' build process running docker build .
or sh ./verify-w-docker.sh
.
If you prefer to run these commands without docker, you can read Dockerfile and follow the steps manually.
-
Base conventions for a .NET/C# project.
-
Normalize to Linux line endings by default for all files (See .editorconfig and .gitattributes).
-
Ignore from git and docker files with the convention that denotes secrets (See .gitignore and .dockerignore).
-
Prettier validation for all supported files.
-
Editor Config validation using
dotnet-format
andeclint
. -
Launch and debug settings for VS Code (.vscode) and Visual Studio (launchSettings.json).
-
Custom color for VS Code (using Peacock, see settings.json).
-
Format validation, build and test run in CI process.
-
Generation of the docker images following Doppler convention and publish them to Docker Hub (See build-n-publish.sh).
-
Generation of
version.txt
file with the image version inwwwroot
. Also, expose it using static files middleware. -
demo.http to easily add manual tests for the exposed API with VS Code REST Client.
-
Exposing only HTTP (not HTTPS) because that is the responsibility of our reverse proxy.
-
Allow overriding project settings based on our Doppler conventions.
-
Expose Swagger (with support for segment prefix).
-
Including an example of a self-hosting integration test.
By the moment it is only an example that could be used to create new APIs or even services.
A simple way of doing that is copy all the files and then:
-
Delete all
bin
andobj
folders -
Rename all the files and folder names from
Doppler.HelloMicroservice
to the desired names.For example
Doppler.HelloMicroservice.Test/Doppler.HelloMicroservice.Test.csproj
toDoppler.SuperAPI.Test/Doppler.SuperAPI.Test.csproj
-
Case sensitive search and replace all occurrences of
Doppler.HelloMicroservice
to the desired name.IMPORTANT: Some files are not included in the VS Solution, you should search for
Doppler.HelloMicroservice
in ALL the files. -
Case sensitive search and replace all occurrences of
hello-microservice
to the desired name.IMPORTANT: Some files are not included in the VS Solution, you should search for
hello-microservice
in ALL the files. -
Replace the IDs in the .sln file.
We have
{FC79D827-86F3-4F93-8064-C4927957A1D2}
for the main project,{646F92A1-8B19-43E0-BED1-8A56B6FB9352}
for the test project,{9BE75F53-F47E-4B35-9560-AA039EBC5B1C}
for the solution files and{A6DDDBE4-738F-4679-809B-D7786BD5E7E5}
for the solution itself. It is possible generate new IDs using any tool, for example Online GUID / UUID Generator
We are using the GitHub organizations FromDoppler (for public code) and MakingSense (for private code).
Create a new empty project there, and create a PR to push the updated files. It should start a CI process in our Jenkins server.
In GitHub Branches Settings add a new protection rule for the main
branch.
With the following configuration:
- Branch name pattern:
main
- Require status checks to pass before merging: checked
- Require branches to be up to date before merging: checked
- Status checks that are required:
continuous-integration/jenkins/pr-head
- Include administrators: checked
At this point, the CI process already generated a Docker Hub repository and we should configure the WebHooks to enable the auto-redeploy in our environments.
IMPORTANT: You need the credentials of dopplerdock
Docker Hub account. Ask for them.
Open the Webhooks configuration page of this new repository (this is the URL for hello-microservice repository: https://hub.docker.com/repository/docker/dopplerdock/hello-microservice/webhooks) and create the webhooks for production and test environments:
- cd-helper-production
https://apis.fromdoppler.com/cd-helper/hooks/{{REEMPLACE-THE-SECRET-HERE}}/
- cd-helper-test
https://apisqa.fromdoppler.net/cd-helper/hooks/{{REEMPLACE-THE-SECRET-HERE}}/
IMPORTANT: You can see the secrets in other Docker Hub repositories, for example in CD-Helper's one.
We should add the stack to Doppler Swarm repository, it is possible using hello-stack
as reference. Using search in files is recommended to find all the places to update.