README
¶
iracelog-service-manager-go
This repository contains the service backend for processing gRPC messages of the iRacelog project.
This project is the replacement of Python implementation of iracelog-service-manager in the iRacelog project
Initial Setup
This section is intended to help developers and contributors get a working copy of
iracelog-service-manager-go on their end
Clone this repository
git clone https://github.com/mpapenbr/iracelog-service-manager-go
cd iracelog-service-manager-go
Option: Devcontainer with VS Code (recommended)
After cloning the repository you already changed into the project dir iracelog-service-manager-go.
Enter
code .
to fire up VS Code. VS Code will detect the Devcontainer configuration and ask wheter to restart the folder using the devcontainer. Please confirm. After downloading and configuring the container with the required tools and VS code plugins you're (almost) ready to go.
Local Development
This section will guide you to setup a fully-functional local copy of iracelog-service-manager-go
on your end and teach you how to use it! Make sure you have installed
golangci-lint before following this section!
Note: This section relies on the usage of Makefile. If you
can't (or don't) use Makefile, you can follow along by running the internal commands
from iracelog-service-manager-go's Makefile (most of which are
OS-independent)!
Installing dependencies
To install all dependencies associated with iracelog-service-manager-go, run the
command
make install
Setting up pre-commit
For a watered-down explanation, pre-commit hooks are an abstraction over
git-hooks, allowing you to define a series of commands (or checks), that
would be automatically run every time you use the git commit command.
The pre-commit hooks used by iracelog-service-manager-go are located within the
.pre-commit-config.yml file. These hooks are configured to run;
- Series of basic checks (JSON, YAML, XML file schema validation)
- Checks for merge conflicts, and possible leaks of private keys
- File formatters - whitespace trimming, end-of-file fixers
- Checks for executable scripts
- JSON formatters
- Code Formatters
- Test-suite
To install pre-commit, simply use the Makefile command
make local-setup
Note: To install (and use) pre-commit, make sure you have the latest stable
versions of Python and pip installed!
The Makefile command will install pre-commit on your PC, and attach it to git
hooks -- ensuring pre-commit checks are run every time you use the git commit command!
Using pre-commit
The previous section guided you to install pre-commit, ensuring pre-commit runs implicitly *before every commit*.
However, if needed, you can use the run command to forcibly run pre-commit on all
staged files (i.e. files in staging area in git).
To manually run pre-commit on all files (including unstaged files), use
pre-commit run --all-files
Using Code Formatters
Code formatters format your code to match pre-decided conventions. To run automated code formatters, use the Makefile command
make codestyle
Using Code Linters
Linters are tools that analyze source code for possible errors. This includes typos, code formatting, syntax errors, calls to deprecated functions, potential security vulnerabilities, and more!
To run pre-configured linters, use the command
make lint
Running Tests
Tests in iracelog-service-manager-go are classified as fast and slow - depending
on how quick they are to execute.
To selectively run tests from either test group, use the Makefile command
make fast-test
OR
make slow-test
Alternatively, to run the complete test-suite -- i.e. fast and slow tests at one go, use the command
make test
Running the Test-Suite
The test-suite is simply a wrapper to run linters, stylecheckers and all tests
at once!
To run the test-suite, use the command
make test-suite
In simpler terms, running the test-suite is a combination of running linters
and all tests one after the other!
Additional Resources
TLS management
In general the app is designed to run behind a proxy. The proxy takes care about the TLS termination. In the productive environment this is done by Traefik using Let's encrypt certificates.
There is another entry point available bypassing the proxy. This entry point is dedicated for the racelogger and can be used with self signed certificates or by using the Let's encrypt certs.
| Param | Description | Usage |
|---|---|---|
--tls-server-addr |
gRPC server listen address (TLS) | Traefik + Self-signed |
--tls-ca |
file containing the root certificate | Self-signed |
--tls-key |
file containing the server key | Self-signed |
--tls-cert |
file containing the server cert | Self-signed |
--traefik-certs |
file containing LE-cert managed by Traefik | Traefik |
--traefik-cert-domain |
the domain containing the cert | Traefik |
Self signed
The createCerts.sh script shows an example for creating the required files for both server and client certs to be used for localhost.
The generated rootCA.pem needs to configured on both sides, server and client.
Note: You have to adjust the localhost value to the destination host when generating the cert.
Makefile help
Tap for a list of Makefile commands
| Command | Description | Prerequisites |
|---|---|---|
help |
Generate help dialog listing all Makefile commands with description | NA |
local-setup |
Setup development environment locally | python, pip |
install |
Fetch project dependencies | NA |
codestyle |
Run code-formatters | golangci-lint |
lint |
Check codestyle and run linters | golangci-lint |
test |
Run all tests | NA |
fast-tests |
Selectively run fast tests | NA |
slow-tests |
Selectively run slow tests | NA |
test-suite |
Check codestyle, run linters and all tests | golangci-lint |
run |
Run iracelog-service-manager-go | NA |
Optionally, to see a list of all Makefile commands, and a short description of what they do, you can simply run
make
Which is equivalent to;
make help
Both of which will list out all Makefile commands available, and a short description of what they do!
Generating Binaries
To generate binaries for multiple OS/architectures, simply run
goreleaser build
The command will generate binaries for Linux, Windows and Mac targetting multiple
architectures at once! The binaries, once generated will be stored in the dist
directory inside the project directory.
Adjust the .goreleaser.yml to fit your needs.
See goreleaser for details.
Generating Images
goreleaser is also used to create archives and docker images. This can be done by
goreleaser release
The current .goreleaser.yml is target for creating docker images and artefacts to be created by Github actions.
Running iracelog-service-manager-go
To run iracelog-service-manager-go, use the command
make run
Additionally, you can pass any additional command-line arguments (if needed) as the
argument "q". For example;
make run q="--help"
OR
make run q="--version"
Releases
You can check out a list of previous releases on the Github Releases page.
Semantic versioning with Release Drafter
What is Semantic Versioning?
Semantic versioning is a versioning scheme aimed at making software management easier. Following semantic versioning, version identifiers are divided into three parts;
<major>.<minor>.<patch>
MAJOR version when you make incompatible API changes [breaking changes]
MINOR version when you add functionality in a backwards compatible manner [more features]
PATCH version when you make backwards compatible bug fixes [bug fixes and stuff]
For a more detailed description, head over to semver.org
Release Drafter automatically updates the release version as pull requests are merged.
Labels allowed;
major: Affects the<major>version number for semantic versioningminor,enhancement,update,feature: Affects the<minor>version number for semantic versioning- all other labels affect the
<patch>version number
Whenever a pull request with one of these labels is merged to the main branch,
the corresponding version number will be bumped by one digit!
List of Labels
Pull requests once merged, will be classified into categories by release-drafter based on pull request labels
This is managed by the release-drafter.yml config file.
| Label | Title in Releases |
|---|---|
security |
🔒 Security |
enhancement, feature, update |
🚀 Updates |
bug, bugfix, fix |
🐛 Bug Fixes |
documentation, docs |
📝 Documentation |
wip, in-progress, incomplete, partial, hotfix |
🚧 Work in Progress |
dependencies, dependency |
📦 Dependencies |
refactoring, refactor, tests, testing |
🧪 Tests and Refactor |
build, ci, pipeline |
🤖 CI/CD and Pipelines |
The labels bug, enhancement, and documentation are automatically created by Github
for repositories. Dependabot will implicitly create the
dependencies label with the first pull request raised by it.
The remaining labels can be created as needed!
Credits
iracelog-service-manager-go is powered by a template generated using cookiecutter-go which is based on go-template
Documentation
Source Files
Directories