From e9880ba128474ef2df85f660f4229413122c1adf Mon Sep 17 00:00:00 2001 From: Jory Irving Date: Wed, 10 Jan 2024 12:51:15 -0700 Subject: [PATCH] Add readme-tempalte --- .github/scripts/json-to-yaml.py | 26 ++++++ .github/scripts/templates/README.md.j2 | 119 +++++++++++++++++++++++++ 2 files changed, 145 insertions(+) create mode 100644 .github/scripts/json-to-yaml.py create mode 100644 .github/scripts/templates/README.md.j2 diff --git a/.github/scripts/json-to-yaml.py b/.github/scripts/json-to-yaml.py new file mode 100644 index 0000000..bf52ec4 --- /dev/null +++ b/.github/scripts/json-to-yaml.py @@ -0,0 +1,26 @@ + +import os +import json +import yaml + +def json_to_yaml(subdir, file): + obj = None + + json_file = os.path.join(subdir, file) + with open(json_file) as f: + obj = json.load(f) + + yaml_file = os.path.join(subdir, "metadata.yaml") + with open(yaml_file, "w") as f: + yaml.dump(obj, f) + + os.remove(json_file) + + +if __name__ == "__main__": + + for subdir, dirs, files in os.walk("./apps"): + for f in files: + if f != "metadata.json": + continue + json_to_yaml(subdir, f) diff --git a/.github/scripts/templates/README.md.j2 b/.github/scripts/templates/README.md.j2 new file mode 100644 index 0000000..5e8f16c --- /dev/null +++ b/.github/scripts/templates/README.md.j2 @@ -0,0 +1,119 @@ + +
+ + +## Containers + +_An opinionated collection of container images_ + +
+ +
+ +![GitHub Repo stars](https://img.shields.io/github/stars/LilDrunkenSmurf/containers?style=for-the-badge) +![GitHub forks](https://img.shields.io/github/forks/LilDrunkenSmurf/containers?style=for-the-badge) +![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/LilDrunkenSmurf/containers/release-scheduled.yaml?style=for-the-badge&label=Scheduled%20Release) + +
+ +Welcome to our container images, if looking for a container start by [browsing the GitHub Packages page for this repo's packages](https://github.com/LilDrunkenSmurf?tab=packages&repo_name=containers). + +## Mission statement + +The goal of this project is to support [semantically versioned](https://semver.org/), [rootless](https://rootlesscontaine.rs/), and [multiple architecture](https://www.docker.com/blog/multi-arch-build-and-images-the-simple-way/) containers for various applications. + +We also try to adhere to a [KISS principle](https://en.wikipedia.org/wiki/KISS_principle), logging to stdout, [one process per container](https://testdriven.io/tips/59de3279-4a2d-4556-9cd0-b444249ed31e/), no [s6-overlay](https://github.com/just-containers/s6-overlay) and all images are built on top of [Alpine](https://hub.docker.com/_/alpine) or [Ubuntu](https://hub.docker.com/_/ubuntu). + +## Tag immutability + +The containers built here do not use immutable tags, as least not in the more common way you have seen from [linuxserver.io](https://fleet.linuxserver.io/) or [Bitnami](https://bitnami.com/stacks/containers). + +We do take a similar approach but instead of appending a `-ls69` or `-r420` prefix to the tag we instead insist on pinning to the sha256 digest of the image, while this is not as pretty it is just as functional in making the images immutable. + +| Container | Immutable | +|----------------------------------------------------|-----------| +| `ghcr.io/LilDrunkenSmurf/sonarr:rolling` | ❌ | +| `ghcr.io/LilDrunkenSmurf/sonarr:3.0.8.1507` | ❌ | +| `ghcr.io/LilDrunkenSmurf/sonarr:rolling@sha256:8053...` | ✅ | +| `ghcr.io/LilDrunkenSmurf/sonarr:3.0.8.1507@sha256:8053...` | ✅ | + +_If pinning an image to the sha256 digest, tools like [Renovate](https://github.com/renovatebot/renovate) support updating the container on a digest or application version change._ + +## Passing arguments to a application + +Some applications do not support defining configuration via environment variables and instead only allow certain config to be set in the command line arguments for the app. To circumvent this, for applications that have an `entrypoint.sh` read below. + +1. First read the Kubernetes docs on [defining command and arguments for a Container](https://kubernetes.io/docs/tasks/inject-data-application/define-command-argument-container/). +2. Look up the documentation for the application and find a argument you would like to set. +3. Set the argument in the `args` section, be sure to include `entrypoint.sh` as the first arg and any application specific arguments thereafter. + + ```yaml + args: + - /entrypoint.sh + - --port + - "8080" + ``` + +## Configuration volume + +For applications that need to have persistent configuration data the config volume is hardcoded to `/config` inside the container. This is not able to be changed in most cases. + +## Available Images + +Each Image will be built with a `rolling` tag, along with tags specific to it's version. Available Images Below + +Container | Channel | Image | Latest Tags +--- | --- | --- | --- +{% for image in app_images | sort(attribute="name") -%} +[{{ image.name }}]({{ image.html_url }}) | {{ image.channel }} | ghcr.io/{{ image.owner }}/{{ image.name }} | +{%- set space = joiner(" ") -%} +{%- for tag in image.tags -%} +{{ space() }}![{{ tag }}](https://img.shields.io/badge/{{ tag.replace("-", "--") }}-{% if tag == "latest" %}green{% else %}blue{% endif %}?style=flat-square) +{%- endfor %} +{% endfor %} + +## Contributing + +1. Install [Docker](https://docs.docker.com/get-docker/), [Taskfile](https://taskfile.dev/) & [Cuelang](https://cuelang.org/) +2. Get familiar with the structure of the repositroy +3. Find a similar application in the apps directory +4. Copy & Paste an application and update the directory name +5. Update `metadata.json`, `Dockerfile`, `ci/latest.sh`, `ci/goss.yaml` and make it suit the application build +6. Include any additional files if required +7. Use Taskfile to build and test your image + + ```ruby + task APP=sonarr CHANNEL=main test + ``` + +### Automated tags + +Here's an example of how tags are created in the GitHub workflows, be careful with `metadata.json` as it does affect the outcome of how the tags will be created when the application is built. + +| Application | Channel | Stable | Base | Generated Tag | +|-------------|-----------|---------|---------|-----------------------------| +| `ubuntu` | `focal` | `true` | `true` | `ubuntu:focal-rolling` | +| `ubuntu` | `focal` | `true` | `true` | `ubuntu:focal-19880312` | +| `alpine` | `3.16` | `true` | `true` | `alpine:rolling` | +| `alpine` | `3.16` | `true` | `true` | `alpine:3.16.0` | +| `sonarr` | `develop` | `false` | `false` | `sonarr-develop:3.0.8.1538` | +| `sonarr` | `develop` | `false` | `false` | `sonarr-develop:rolling` | +| `sonarr` | `main` | `true` | `false` | `sonarr:3.0.8.1507` | +| `sonarr` | `main` | `true` | `false` | `sonarr:rolling` | + +## Deprecations + +Containers here can be **deprecated** at any point, this could be for any reason described below. + +1. The upstream application is **no longer actively developed** +2. The upstream application has an **official upstream container** that follows closely to the mission statement described here +3. The upstream application has been **replaced with a better alternative** +4. The **maintenance burden** of keeping the container here **is too bothersome** + +**Note**: Deprecated containers will remained published to this repo for 6 months after which they will be pruned. +## Credits + +A lot of inspiration and ideas are thanks to the hard work of [hotio.dev](https://hotio.dev/) and [linuxserver.io](https://www.linuxserver.io/) contributors.