No hay una bala de plata aquí hasta donde yo sé. Todas las soluciones a continuación funcionan, pero requieren que se informe al usuario sobre cómo recuperar la documentación.
No hay una forma estándar de hacerlo .
La iniciativa de contenedor abierto ha creado una anotación de especificaciones de imagen que sugiere que
- Se debe proporcionar un enlace a más información sobre la imagen en una etiqueta llamada
org.opencontainers.image.documentation.
- Se debe proporcionar una descripción del software empaquetado dentro del contenedor en una etiqueta llamada
org.opencontainers.image.description
Según OCI, una de las variaciones de la opción 1 a continuación es correcta.
Opción 1: Proporcionar un enlace en una etiqueta (Preferido por OCI )
Suponiendo que el Dockerfile y los activos relacionados están controlados por la versión en un repositorio git que es de acceso público (por ejemplo, en github), ese repositorio git también podría contener un archivo README.md. Si tiene una tubería conectada al repositorio que construye y publica la imagen de Docker en un registro automáticamente, puede configurar el comando de compilación de Docker para agregar una etiqueta con un enlace a la documentación de la siguiente manera
# Get the current commit id
commit=$(git rev-parse HEAD)
# Build docker image and attach a link to the Readme as a label
docker build -t myimagename:myversion \
--label "org.opencontainers.image.documentation=https://github.com/<user>/<repo>/blob/$commit/README.md"
Esta solución se vincula a documentación de confirmación específica para esa confirmación particular versionada junto con su Dockerfile. Sin embargo, requiere que el usuario tenga acceso a Internet para poder leer la documentación
Opción 1b: Proporcionar documentación completa en una etiqueta (Preferido por OCI )
Una variación de la opción 1 donde la documentación completa se serializa y se coloca en la etiqueta (no hay restricciones de longitud en las etiquetas). De esta forma, la documentación se incluye con la imagen misma.
Como señaló Jorge Leitao en los comentarios, la especificación de anotación de imagen de OCI especifica el nombre de una etiqueta comoorg.opencontainers.image.description
Opción 2: agrupación de documentación dentro de la imagen
Si prefiere agrupar el archivo Readme.md dentro de la imagen para que sea independiente de cualquier página web externa, tenga en cuenta lo siguiente
Al compilar, asegúrese de copiar el archivo Readme.md a la imagen del acoplador. También cree un script de shell simple describeque genere el archivo Readme.md
describir
#!/usr/bin/env sh
cat /docs/Readme.md
Adiciones de archivos Docker
...
COPY Readme.md /docs/Readme.md
COPY describe /opt/bin/describe
RUN chmod +x /opt/bin/describe
ENV PATH="/opt/bin:${PATH}"
...
Un usuario que tenga su imagen de Docker ahora puede ejecutar el siguiente comando para que se envíe la rebaja a stdout
docker run myimage:version describe
Esta solución incluye la documentación de esta versión particular de la imagen dentro de la imagen y se puede recuperar sin ninguna dependencia externa.