FROM registry.fedoraproject.org/fedora:rawhide

ARG NAME=mycontainer
ARG VERSION=0
ARG ARCH=x86_64
LABEL   com.redhat.component="$NAME" \
        name="$FGC/$NAME" \
        version="$VERSION" \
        architecture="$ARCH" \
        run="podman run -p 1337:1337 IMAGE" \
        summary="mycontainer exposes something on port 1337." \
        maintainer="Christian Glombek <lorbus@fedoraproject.org>"

EXPOSE 1337

RUN dnf -y --setopt=tsflags=nodocs install mypackage && \
    dnf clean all

COPY root/help.1 /
COPY script.sh /usr/bin/

CMD ["/usr/bin/script.sh"]

ສິ່ງນີ້ຊ່ວຍຮັບປະກັນວ່າຮູບພາບພື້ນຖານ (base image) ມາຈາກໃສ ເມື່ອຖືກສ້າງໂດຍບໍລິການ build ຫຼື ເມື່ອຜູ້ໃຊ້ສ້າງຄືນໃໝ່.

ສຳລັບຮູບພາບແບບຊັ້ນ (layered images) ສ່ວນໃຫຍ່ທີ່ສ້າງໂດຍ https://docs.pagure.org/releng/layered_image_build_service.html[Fedora Layered Docker Image Build Service], ແຖວ FROM ຈະໃຊ້ໜຶ່ງໃນຮູບພາບພື້ນຖານຂອງ Fedora ທີ່ມີຢູ່ໃນ https://registry.fedoraproject.org/[Fedora Container Registry]:

``` FROM registry.fedoraproject.org/fedora:latest ```

ນອກນັ້ນ ຍັງສາມາດໃຊ້ຮູບພາບແບບຊັ້ນອື່ນເປັນຊັ້ນພື້ນຖານໄດ້ ດັ່ງໃນຕົວຢ່າງນີ້:

``` FROM registry.fedoraproject.org/f25/kubernetes-master:latest ```


=== ປ້າຍກຳກັບ (Labels)

Dockerfile ມີແນວຄິດເລື່ອງ https://docs.docker.com/engine/reference/builder/#label[LABEL] ເຊິ່ງສາມາດເພີ່ມຂໍ້ມູນເມຕາດາຕ້າ (metadata) ໃຫ້ກັບຮູບພາບໃນຮູບແບບຄູ່ Key-Value. ຄຳແນະນຳຂອງ Fedora ກ່ຽວກັບ LABEL ແມ່ນອີງຕາມມາດຕະຖານ http://www.projectatomic.io/[Project Atomic] https://github.com/projectatomic/ContainerApplicationGenericLabels[Container Application Generic Labels] ສຳລັບການກຳນົດ LABEL.

LABELs ທີ່ '''ຈຳເປັນ''' ສຳລັບ Fedora Layered Image ມີດັ່ງນີ້:

[cols="2*", options"header"]
|===
|ຊື່
|ຄຳອະທິບາຍ

|com.redhat.component
|ຊື່ສ່ວນປະກອບໃນ Bugzilla ທີ່ຜູ້ໃຊ້ຄວນລາຍງານບັນຫາຂອງຄອນເທນເນີນີ້.

|name
|ຊື່ຂອງຮູບພາບ

|version
|ເວີຊັນຂອງຮູບພາບ

|architecture
|ສະຖາປັດຕະຍະກຳທີ່ຊອບແວໃນຮູບພາບນີ້ຮອງຮັບ (ທາງເລືອກ: ຖ້າຂ້າມໄປ, ມັນຈະຖືກສ້າງສຳລັບທຸກສະຖາປັດຕະຍະກຳທີ່ Fedora ຮອງຮັບ)

|maintainer
|ຊື່ ແລະ ອີເມລ ຂອງຜູ້ດູແລ (ປົກກະຕິແລ້ວແມ່ນຜູ້ສົ່ງຜົນງານ)

|run ຫຼື usage
|ໃຫ້ຄຳສັ່ງ run ແບບ Atomic ຫຼື ຕົວຢ່າງການເຮັດວຽກຂອງຄອນເທນເນີທີ່ຄົນສາມາດອ່ານເຂົ້າໃຈໄດ້

|summary
|ຄຳອະທິບາຍຫຍໍ້ຂອງຮູບພາບ.
|===

ປ້າຍກຳກັບ '''ທາງເລືອກ''' ສຳລັບ Fedora Layered Images

[cols="2*", options"header"]
|===
|ຊື່
|ຄຳອະທິບາຍ

|install
|ໃຊ້ສຳລັບຄຳສັ່ງ "atomic install". ບໍ່ໄດ້ໃຊ້ສຳລັບ system containers.

|uninstall
|ໃຊ້ສຳລັບຄຳສັ່ງ "atomic uninstall". ຈຳເປັນຕ້ອງມີຖ້າມີການໃຊ້ Install.

|url
|URL ທີ່ຜູ້ໃຊ້ສາມາດຊອກຫາຂໍ້ມູນເພີ່ມເຕີມກ່ຽວກັບຮູບພາບ.

|help
|ຄຳສັ່ງທີ່ສາມາດສັ່ງໃຫ້ສະແດງຂໍ້ມູນການຊ່ວຍເຫຼືອ (Help).

|atomic.type
|ໃຊ້ສຳລັບ system containers, ເບິ່ງລາຍລະອຽດດ້ານລຸ່ມ.

|Generics
|https://github.com/projectatomic/ContainerApplicationGenericLabels[Container Application Generic Labels] ໃດໆທີ່ເໝາະສົມກັບຄອນເທນເນີ ເຊັ່ນ "stop", "debug", ຫຼື "changelog-url"
|===

ເບິ່ງຂໍ້ກຳນົດຂອງ LABEL (LABEL SPECIFICATION) ດ້ານລຸ່ມສຳລັບລາຍລະອຽດເພີ່ມເຕີມກ່ຽວກັບສິ່ງທີ່ຈຳເປັນໃນແຕ່ລະປ້າຍກຳກັບ.

{{admon/note|Dockerfile Label Guidelines Upstream| LABEL ທີ່ໃຊ້ຢູ່ນີ້ແມ່ນການປັບໃຊ້ຂອງ Fedora ຈາກໂຄງການຕົ້ນທາງ https://projectatomic.io[Project Atomic] ທີ່ພະຍາຍາມກຳນົດ https://github.com/projectatomic/ContainerApplicationGenericLabels[Container Application Generic Labels] ລວມເຖິງ http://docs.projectatomic.io/container-best-practices/[Container Best Practices]. }}

ໃນອະດີດ LABEL ເຫຼົ່ານີ້ຕ້ອງຖືກກຳນົດໃນແຖວດຽວກັນຂອງ Dockerfile ເພື່ອບໍ່ໃຫ້ເກີດຊັ້ນ (layers) ເພີ່ມເຕີມໃນການ build. ແຕ່ OSBS ເວີຊັນໃໝ່ໆຈະລວມທຸກຊັ້ນທີ່ສ້າງຂຶ້ນເທິງຮູບພາບຫຼັກໃຫ້ເປັນຊັ້ນດຽວ, ໝາຍຄວາມວ່າບໍ່ຈຳເປັນຕ້ອງໃສ່ທຸກ LABEL ຫຼື ຄຳສັ່ງ RUN ໄວ້ໃນແຖວດຽວກັນອີກຕໍ່ໄປ.

ຕໍ່ໄປນີ້ແມ່ນຕົວຢ່າງ Dockerfile ແບບງ່າຍໆ ທີ່ມີ LABEL ທີ່ຈຳເປັນຄົບຖ້ວນ:

[source]
----
FROM registry.fedoraproject.org/fedora:rawhide

ARG NAME=mycontainer
ARG VERSION=0
ARG ARCH=x86_64
LABEL   com.redhat.component="$NAME" \
        name="$FGC/$NAME" \
        version="$VERSION" \
        architecture="$ARCH" \
        run="podman run -p 1337:1337 IMAGE" \
        summary="mycontainer exposes something on port 1337." \
        maintainer="Christian Glombek <lorbus@fedoraproject.org>"

EXPOSE 1337

RUN dnf -y --setopt=tsflags=nodocs install mypackage && \
    dnf clean all

COPY root/help.1 /
COPY script.sh /usr/bin/

CMD ["/usr/bin/script.sh"]
----


=== ຂໍ້ກຳນົດຂອງ LABEL

ລາຍລະອຽດເພີ່ມເຕີມກ່ຽວກັບວິທີການໃສ່ຂໍ້ມູນໃນແຕ່ລະປ້າຍກຳກັບ.

'''com.redhat.component''': ສ່ວນປະກອບໃນ Bugzilla ທີ່ມີຢູ່ແລ້ວ ເພື່ອໃຊ້ໃນການລາຍງານບັນຫາຂອງຮູບພາບນີ້.

'''name''': ຊື່ຂອງຮູບພາບ. ຖ້າຮູບພາບນີ້ມາແທນທີ່ RPM ມາດຕະຖານ, ມັນຄວນຈະມີຊື່ດຽວກັນກັບ RPM ນັ້ນ. ຖ້າບໍ່ດັ່ງນັ້ນ, ກະລຸນາເບິ່ງຄຳແນະນຳການຕັ້ງຊື່ດ້ານເທິງ.

'''version''': ປົກກະຕິແມ່ນ 0. ດຶງຂໍ້ມູນມາຈາກຕົວປ່ຽນ ARG. ເບິ່ງຄຳອະທິບາຍໃນສ່ວນ "VERSIONING" ດ້ານລຸ່ມ.

'''architecture''': ປົກກະຕິແມ່ນ "x86_64", ຍົກເວັ້ນແຕ່ຄອນເທນເນີຈະຮອງຮັບສະຖາປັດຕະຍະກຳອື່ນ ຫຼື ທັງໝົດ.

'''usage''': ຕົວຢ່າງຄຳສັ່ງທີ່ຄົນອ່ານເຂົ້າໃຈໄດ້ເພື່ອໃຊ້ເອີ້ນຄອນເທນເນີ. ຈຳເປັນຕ້ອງມີຖ້າບໍ່ມີປ້າຍກຳກັບ run. ຄວນລວມເອົາຕົວເລືອກຕ່າງໆ ເຊັ່ນ ports, volumes, ແລະ ພະລາມິເຕີທີ່ຈຳເປັນ. ທ່ານສາມາດໃຊ້ container runtime ໃດກໍໄດ້ເປັນຕົວຢ່າງ. ຕົວຢ່າງຈາກຄອນເທນເນີ OwnCloud:

    usage="docker run -d -P -v owncloud-data:/var/lib/owncloud -v owncloud-config:/etc/owncloud owncloud"

'''summary''': ຄຳອະທິບາຍຫຍໍ້ຂອງຮູບພາບ, ເພື່ອໃຫ້ສາມາດຄົ້ນຫາໄດ້ເມື່ອມີ registry ທີ່ມີລະບົບຄົ້ນຫາ. ກະລຸນາໃສ່ຄຳສຳຄັນ (keywords) ທີ່ກ່ຽວຂ້ອງ.

'''run''': ຄຳສັ່ງເພື່ອເອີ້ນໃຊ້ຄອນເທນເນີ ທີ່ເໝາະສຳລັບການໃຊ້ຜ່ານ https://github.com/projectatomic/atomic[Atomic CLI], ລວມທັງ placeholders ແລະ ໂຄ້ດ atomic-run ທີ່ຝັງໄວ້. ຕ້ອງສາມາດເຮັດວຽກໄດ້ໃນລະບົບ Fedora Atomic ທີ່ເໝາະສົມ. ຈຳເປັນຕ້ອງມີຖ້າບໍ່ມີ "usage". ຕົວຢ່າງສຳລັບຄອນເທນເນີ Cockpit:

    run="/usr/bin/docker run -d --privileged --pid=host -v /:/host IMAGE /container/atomic-run --local-ssh"

'''install''': ຄອນເທນເນີອາດຕ້ອງການການກຽມລະບົບ host ກ່ອນຈະສາມາດເຮັດວຽກໄດ້. ໃນກໍລະນີນີ, ປ້າຍກຳກັບ install ຈະມີປະໂຫຍດໃນການກຳນົດວ່າຕ້ອງເຮັດຫຍັງແດ່ໃນ host ເພື່ອກຽມຄວາມພ້ອມ. ຂັ້ນຕອນຄວນມີໜ້ອຍທີ່ສຸດເທົ່າທີ່ຈະເປັນໄປໄດ້ ແລະ ບໍ່ຄວນລວມເອົາຂັ້ນຕອນທີ່ບໍ່ຈຳເປັນ. ຖ້າມີການໃຊ້ປ້າຍກຳກັບ install, ມັນຕ້ອງໄດ້ຮັບການທົດສອບ ແລະ ເຮັດວຽກຮ່ວມກັບ https://github.com/projectatomic/atomic[Atomic CLI] ໄດ້. ນອກນັ້ນ ຄວນມີປ້າຍກຳກັບ uninstall ເພື່ອລຶບລ້າງສິ່ງທີ່ install ໄດ້ເຮັດໄວ້. ກະລຸນາເບິ່ງ https://github.com/projectatomic/atomic#atomic-install[ເອກະສານຕົ້ນທາງ] ສຳລັບຂໍ້ມູນເພີ່ມເຕີມ. ຕົວຢ່າງສຳລັບຄອນເທນເນີ Cockpit:

    install="/usr/bin/docker run --rm --privileged -v /:/host IMAGE /container/atomic-install"

'''uninstall''': ຖ້າຄອນເທນເນີມີປ້າຍກຳກັບ install, ສ່ວນໃຫຍ່ແລ້ວຈະຕ້ອງມີປ້າຍກຳກັບ uninstall ເພື່ອລຶບໄຟລ໌ ແລະ/ຫຼື ລຶບລ້າງການຕັ້ງຄ່າຕ່າງໆທີ່ເຮັດໄວ້ໃນລະບົບ host. ບໍ່ຈຳເປັນຕ້ອງລຶບໄຟລ໌ທີ່ອາດມີຂໍ້ມູນຜູ້ໃຊ້. ໃນບາງກໍລະນີທີ່ບໍ່ມີໄຟລ໌ ຫຼື ການຕັ້ງຄ່າໃຫ້ລຶບ, ປ້າຍກຳກັບ uninstall ກໍອາດບໍ່ຈຳເປັນ. ຖ້າມີປ້າຍກຳກັບ uninstall, ມັນຕ້ອງໄດ້ຮັບການທົດສອບ ແລະ ເຮັດວຽກຮ່ວມກັບ https://github.com/projectatomic/atomic[Atomic CLI] ໄດ້. ກະລຸນາເບິ່ງ https://github.com/projectatomic/atomic#atomic-uninstall[ເອກະສານຕົ້ນທາງ] ສຳລັບຂໍ້ມູນເພີ່ມເຕີມ.

    uninstall="/usr/bin/docker run --rm --privileged -v /:/host IMAGE /container/atomic-uninstall"

'''url''': URL ທີ່ຜູ້ໃຊ້ສາມາດເບິ່ງຂໍ້ມູນເພີ່ມເຕີມກ່ຽວກັບຮູບພາບ ເຊັ່ນ github, pagure repository, ຫຼື ເອກະສານຂອງຊອບແວ.

'''help''': ຄຳສັ່ງທີ່ສາມາດສັ່ງໃຫ້ສະແດງໜ້າ man page ຫຼື ຂໍ້ມູນ "help" ອື່ນໆ. ຖ້າມີ, ຕ້ອງໄດ້ຮັບການທົດສອບດ້ວຍ `atomic help`. ຖ້າທ່ານມີຄຳສັ່ງ help ແລ້ວ, ກໍບໍ່ຈຳເປັນຕ້ອງມີ Help File ອີກ (ເບິ່ງດ້ານລຸ່ມ).


=== ການກຳນົດເວີຊັນ (Versioning)

ໃນສ່ວນກ່ອນໜ້ານີ້ໄດ້ເວົ້າເຖິງ LABEL, ຫນຶ່ງໃນນັ້ນແມ່ນ Version ທີ່ຖືກກຳນົດໃນຕົວຢ່າງໂດຍໃຊ້ຕົວປ່ຽນ `ENV` `VERSION` ເຊິ່ງໃນເວລານີ້ຕ້ອງກຳນົດເປັນ `0`. OSBS ຈະຈັດການເພີ່ມເລກ release ໂດຍອັດຕະໂນມັດສຳລັບເວີຊັນຂອງຮູບພາບຄອນເທນເນີນັ້ນ.

ໃນເວລານີ້ ຍັງບໍ່ມີວິທີໃສ່ຄ່າ `Version`/`VERSION` ໃຫ້ກົງກັບເວີຊັນຫຼ້າສຸດຂອງ RPM ຫຼັກຂອງຮູບພາບຄອນເທນເນີໂດຍອັດຕະໂນມັດ. ສິ່ງນີ້ກຳລັງຢູ່ໃນ https://pagure.io/atomic-wg/issue/249[ແຜນການພັດທະນາ (roadmap)].

ເປັນຫຍັງຈຶ່ງຈຳເປັນ?

ຖ້າພວກເຮົາກຳນົດ LABEL `Version` ໃຫ້ກົງກັບເວີຊັນຂອງ RPM ໃນເວລາທີ່ກວດສອບຮູບພາບຄອນເທນເນີ, ຜູ້ດູແລຈະຕ້ອງມາອັບເດດມັນດ້ວຍຕົນເອງທຸກຄັ້ງທີ່ມີການອັບເດດ RPM ເຊິ່ງບໍ່ສະດວກ ແລະ ອາດເກີດຂໍ້ຜິດພາດໄດ້ງ່າຍ. ນອກຈາກນັ້ນ, ຍັງມີຄວາມເປັນໄປໄດ້ທີ່ເວີຊັນຂອງ RPM ອາດຖືກອັບເດດໂດຍການ rebuild ຮູບພາບແບບຊັ້ນໂດຍອັດຕະໂນມັດ ໂດຍທີ່ຜູ້ດູແລບໍ່ສາມາດອັບເດດ `Dockerfile` ໄດ້ທັນເວລາ (ການ Rebuild ອັດຕະໂນມັດແມ່ນເຮັດໂດຍ https://docs.pagure.org/releng/[Release Engineering] ເພື່ອດຶງເອົາການອັບເດດຄວາມປອດໄພມາໃຊ້). ຖ້າສິ່ງນີ້ເກີດຂຶ້ນ, ເວີຊັນຂອງຮູບພາບຄອນເທນເນີຈະບໍ່ກົງກັບເວີຊັນຂອງຊອບແວທີ່ມັນໃຫ້ບໍລິການ ເຊິ່ງຈະສ້າງຄວາມສັບສົນ ແລະ ອາດສົ່ງຜົນກະທົບທາງລົບຕໍ່ຜູ້ໃຊ້. ດັ່ງນັ້ນ, ໃນເວລານີ້ ພວກເຮົາຈຶ່ງກຳນົດວ່າເລກເວີຊັນຂອງຄອນເທນເນີ ຍັງບໍ່ມີຄວາມໝາຍສຳຄັນເທື່ອ ແຕ່ຈະເຮັດໃຫ້ມັນມີຄວາມໝາຍໂດຍໄວທີ່ສຸດ.


=== CMD / ENTRYPOINT

ອີກຢ່າງໜຶ່ງທີ່ຈຳເປັນແມ່ນການກຳນົດ CMD ຫຼື ENTRYPOINT ເພື່ອໃຫ້ເມື່ອຜູ້ໃຊ້ສັ່ງຄຳສັ່ງ (ຕົວຢ່າງ), ມັນຈະເຮັດວຽກຕາມທີ່ຄາດໄວ້:

``` docker run registry.fedoraproject.org/f25/myawesomecontainer ```

ສຳລັບຂໍ້ມູນເພີ່ມເຕີມກ່ຽວກັບຄຳສັ່ງເຫຼົ່ານີ້, ກະລຸນາເບິ່ງເອກະສານຕົ້ນທາງ https://docs.docker.com/engine/reference/builder/[Dockerfile documentation].


=== ໂວນລຸ່ມ (Volumes)

ການໃຊ້ container volumes ສຳລັບຂໍ້ມູນທີ່ຕ້ອງການຄວາມຄົງຕົວ (persistent data) ແມ່ນໄດ້ຮັບອະນຸຍາດ ແລະ ແນະນຳໃຫ້ໃຊ້, ແຕ່ຕ້ອງປະຕິບັດຕາມຄຳແນະນຳດັ່ງນີ້:

* ຂໍ້ມູນຜູ້ໃຊ້ໃດໆທີ່ມີຄວາມສ່ຽງຈະສູນຫາຍເມື່ອມີການອັບເດດ '''ຕ້ອງ''' ຖືກເກັບໄວ້ໃນ volume.
* ຂໍ້ມູນການຕັ້ງຄ່າແອັບພລິເຄຊັນໃດໆທີ່ຕ້ອງການຄວາມຄົງຕົວ '''ຕ້ອງ''' ຖືກເກັບໄວ້ໃນ volume. ການຕັ້ງຄ່າຜ່ານຕົວປ່ຽນສະພາບແວດລ້ອມ (environment variables) ກໍສາມາດເຮັດໄດ້ເຊັ່ນກັນ, ທັງແບບໃຊ້ຮ່ວມກັນ ຫຼື ໃຊ້ແທນ volume ການຕັ້ງຄ່າ.
* ທຸກໆ volume ທີ່ລະບຸໄວ້ໃນ Dockerfile '''ຕ້ອງ''' ຖືກລະບຸໄວ້ໃນ Help File ນຳ.
* ຕົວຢ່າງຄຳສັ່ງ run '''ຄວນ''' ມີການຕັ້ງຊື່ volume ແບບຄົງທີ່ (ຕົວຢ່າງ: "docker run -d -v owncloud-data:/var/lib/owncloud -v owncloud-config:/etc/owncloud owncloud")
* Volume '''ຕ້ອງ''' ຖືກກຳນົດໃຫ້ແຄບທີ່ສຸດເທົ່າທີ່ຈະເປັນໄປໄດ້. ໂດຍສະເພາະແລ້ວ, ຍົກເວັ້ນແຕ່ຮູບພາບນັ້ນຈະຖືກອອກແບບມາເພື່ອໃຊ້ເປັນ system container ສຳລັບການບໍລິຫານລະບົບ, volume ຕ້ອງຖືກກຳນົດໃຫ້ mount ໄດ້ສະເພາະໂຟເດີລະບົບທີ່ໃຊ້ສະເພາະໃນຄອນເທນເນີນັ້ນ. ຕົວຢ່າງ: ຄອນເທນເນີຕ້ອງ mount /etc/application-name/ ສຳລັບໄຟລ໌ config, '''ບໍ່ແມ່ນ''' /etc/.

ແຕ່ລະ volume ໃນ Help File '''ຕ້ອງ''' ມີຂໍ້ມູນດັ່ງນີ້:
* Path ເຕັມຂອງ volume
* ເຫດຜົນທີ່ກຳນົດໃຫ້ເປັນ volume (ເຊັ່ນ ເປັນຫຍັງການຕັ້ງຄ່ານີ້ຈຶ່ງຕ້ອງມີຄວາມຄົງຕົວ ຫຼື ລະບຸວ່າຂໍ້ມູນຜູ້ໃຊ້ຖືກເກັບໄວ້ທີ່ນັ້ນ)

Volume ທີ່ລະບຸໃນ Help File '''ຄວນ''' ລວມເອົາຂໍ້ມູນກ່ຽວກັບພື້ນທີ່, ສິດການເຂົ້າເຖິງ (permissions), ແລະ ຄວາມຕ້ອງການດ້ານປະສິດທິພາບ.

ໃນ readme '''ອາດ''' ລະບຸ volume ເພີ່ມເຕີມທີ່ບໍ່ໄດ້ບັງຄັບໃນ Dockerfile, ເຊັ່ນ ບ່ອນເກັບ ssl certificates ທີ່ສ້າງຂຶ້ນໃໝ່.