• Only choose private repositories when the code has business value differentiator logic.

• Use FromDoppler Organization for public repositories and MakingSense for private ones.

• Do not store secrets in the repository

  If you really need to store secrets, store them encrypted using SOPS (see more information).

• Add a README.md file with:

  • Basic description of the project scope

  • Minimal architecture design

  • Guide for contributors

  • Coding standard (When it is not covered by an automated CI process)

• CI/CD from the beginning

  • Setup CI/CD and all environments even before adding any real functionality

  • Branch protection rules to avoid CI bypass

  • Example automated test even before adding any real functionality

• Consider base your repository in one of our base projects See more

• Validate coding standards using automated CI process See more

• Follow Doppler convention for branches and environments See more

• Generate a version.txt file, or another simple way to check what is the code related to the published system. See more details below. See more

• Authenticate users using JWT with our public key [See more]{#doppler-security}

We have some seed projects that can be used as the base for new projects:

• Hello Microservice - Simple .NET API project with CI and CD to Dockerhub

• Hello WebApp - Simple React project (based in CRA) with CI and CD to our CDN

Sometimes, those seed projects can be outdated or we did not prepare a seed yet, so, you can base your project on an existing one, for example:

• Doppler System Usage - Simple Node based AWS Lambda Functions API with CI and CD to our AWS using Serverless

• Doppler Session MFE - Minimal micro-frontend without UI (based in CRA) with CI and CD to our CDN

• Doppler HTML Editor API - Simple .NET API project with CI and CD to Dockerhub with an interesting data access layer architecture based on Dapper

• Doppler Editors WebApp - Simple React project (based in CRA) with CI and CD to our CDN with React Router, a dependency injection layer, React Query and others

We try to automate all our tests and validations in the CI/CD process.

A posible approach to do this is using our dedicated Jenkins service that runs docker based builds and configure branch protection rules in GitHub. You can see an example in Hello Microservice repository.

In general, we have three environments binding to git in this way:

• Resetting the INT branch generates a build and deploys it to the INT environment
• Merging in main generates a build and deploys it to the QA environment
• Creating a tag with format /v\d+.\d+.\d+/ generates a build and deploys it to the Production environment

See a detailed example at Doppler Forms repository

Knowing exactly what source code corresponds to the system we are running use to be very useful.

In our APIs projects we expose a version.txt for that, for example:

GET https://apis.fromdoppler.com/hello/version.txt

# Response
# dopplerdock/hello-microservice:v1.2.4_398120d4821b9da27fd49a485ac58048ee768be8

In our CDN based micro-frontend projects, we expose the version in the manifest file:

GET https://cdn.fromdoppler.com/editors-webapp/asset-manifest-v1.json

# Response
# {
#   "canonicalVersion": "v1.2.5_209dace9d57b9a0f6eef5699fe42e22519083aee",
#   "files": {
#     // . . .
# }

The version format is the following:

<valid_version_info> ::= <full_version>
                      | <artifact_repo> ":" <full_version>
                      | <full_version> "@" <source_code_repo_url>
                      | <artifact_repo> ":" <full_version> "@" <source_code_repo_url>

<full_version> ::= <name_or_version> "+" <source_code_commit_id>
                | <name_or_version> "_" <source_code_commit_id>

<name_or_version> ::= <semver_version>
                    | <name>

<name> ::= "INT"
        | "main"
        | "master"
        | "TEST"
        | "develop"

<semver version> ::= "v" <mayor> "." <minor> "." <patch>

<mayor> ::= <digits>

<minor> ::= <digits>

<patch> ::= <digits>

<artifact_repo> ::= <docker_hub_org> "/" <docker_hub_repo>
# TODO: add more alternatives for <artifact_repo>

# <digits> matches /\d+/
# <docker_hub_org> is any valid DockerHub organization name
# <docker_hub_repo> is any valid DockerHub repository name
# <source_code_repo_url> is any valid URL

# Full regex: /(?:(?<artifact_repo>(?<docker_hub_org>[\w-]+)\/(?<docker_hub_repo>[\w-]+)):)?(?<version_name>(?<version>v(?<mayor>\d+)\.(?<minor>\d+)\.(?<patch>\d+))|(?<name>INT|main|master|TEST|develop))[_\+](?<source_code_commit_id>\w+)(?:@(?<source_code_repo_url>.+))?/

When we need a quick and easy way of authenticate a request, we can validate the request JWT token against a public key.

We have a complete and flexible implementation of this token validation in .NET (for example in Hello Microservice), but it can be easily re-implemented with other frameworks and languages.

To use our generated artifacts, follow the next steps

• Generate a GitHub personal access token with at least read:packages permission
• Set and use the environment variable FROMDOPPLER_GITHUB_PACKAGES_TOKEN with the token generated

• Use or adapt the nuget.config file example into the required repository