oci-tpl

Template for your oci projects with battery included !

Quickstart

to get started with this template, git clone this repo and push to a new origin. you can copy/paste the code below to do so :

printf "enter your repo url\n" \
  && read REPO_URL \
  && printf "enter your project name\n" \
  && read PROJECT_NAME \
  && git clone https://git.hvn.wf/repo-template/oci-tpl.git \
  && git -C bash-tpl remote set-url origin "${REPO_URL}" \
  && mv oci-tpl "${PROJECT_NAME}"

To get the most of the this template, i reccommend to set up a devcontainer environnement for VScode. You can do this easily with Devpod (https://devpod.sh/). you can copy/paste below for a local configuration using podman as container engine. It will also create two shared directory on your home for container-storage and libpod, needed by the devcontaienr (see devcontainer.json) for more detail. Ensure that devpod-cli is installed and in your path before running this :

printf "enter local path to your git repo\n" \
&& read REPO_LOCAl_PATH \
&& mkdir -p "${HOME}"/.devcontainer-volumes/{container-storage,libpod} \
&& devpod provider add docker -o DOCKER_PATH=podman \
&& devpod up "${REPO_LOCAl_PATH]" --ide vscode

voila ! everything is set, you just have to run mise install in vscode terminal to install dev-tools in mise config.

Vscode extension will be automatically installed, check them out in the extension tab, or in the devcontainer.json.

How to

Dev-workflow

I try to follow the least privilege principle when i am devlopping oci image ( https://en.wikipedia.org/wiki/Principle_of_least_privilege ). I run my container using Podman (https://podman.io/) or Kubernetes (https://kubernetes.io/). This could have a influence on my designs. My container are rootless by default (https://rootlesscontaine.rs/)

Env variables/secret

Env variable can be defined in mise.toml, or in the forge if you just need those variable in ci. Secrets are kept on the forge.

Automated tasks

to simplify usual task ( run tst, artifact building, setup thing) i am using mise tasks in dedicated file in .mise-tasks. There is 5 tasks by default :

• test : run test. You must specify the type of test. Available args are unit_tests,security_scan or all. Artifact must be build prior to testing.
• build: build artifact. You must specify artifact tag.
• push: push artifact on oci repo. You must specify artifact tag.
• patch: patch artifact with copacetic.
• symlink-prettier-plugin: symlink /root/.local/share/mise/installs/< plugin_name >/latest/lib/node_modules to ./node_module, so prettier plugin installed via mise could be usable in project directory

To run a task, type mise run <task_name> <args> <option/flag>

CI/CD

CI/CD pipelines are using forgejo action system (https://forgejo.org/docs/next/user/actions/overview/). The syntax is mostly similar to github action, so github action docs should apply in most case (https://github.com/features/actions). Maybe i will do a template for gitlab one day, stay tuned.

Linting/code formating

I use shellcheck and Hadolint to lint bash and Dockerfile code. feel free to check .shelcheckrc and .hadolintlintrc.yaml , if i ever add a linter exception, there should be a comment explaining why.

To ensure my code is properly formated, i use Editorconfig (https://editorconfig.org/) and prettier (https://prettier.io/) with bash and toml plugin. Feel free to check .editorconfig and .prettierrc.yaml to see what i've defined.

I will add a step to format everything in my ci late, for now its just a check, i format things locally.

additional notes

this project is following the semantic versioning guidline (https://semver.org/),as well as Angular conventional commits (https://www.conventionalcommits.org/en/v1.0.0-beta.4/). Gitmojis are here for fun (https://gitmoji.dev/).

I am trying to stick to known best practice to the best of my abilities.

Watch out for new version of this repo, i am always learning !

Useful links

here some external documentation for all the tool used in this template:

• devcontainer: isolated dev environnement in container (https://containers.dev/)
• mise-en-place: swiss army knife for your projects (https://mise.jdx.dev/)
• container-structure-test: Test framwork for container image (https://github.com/GoogleContainerTools/container-structure-test)
• hadolint: Docker linter in Haskell (https://github.com/hadolint/hadolint)
• shellcheck: the bash linter (https://www.shellcheck.net/)
• git-chglog: generate your changelog from conventional commit (https://github.com/git-chglog/git-chglog)
• editorconfig: maitain your coding style from your ide (https://editorconfig.org/)
• prettier: an opinnionated code formatter (https://prettier.io/)
• Forgejo: light and efficient software forge (https://forgejo.org/)