docs: Dockerfile comments (celestiaorg#3145)

Closes celestiaorg#2117

I can think of a few follow-ups after reviewing this Dockerfile:

1. Can we use a different username than `celestia`? Perhaps
`celestia-app` to avoid any user name collision with celestia-node.
2. Does `$BUILDPLATFORM` actually get populated?
3. Can we get rid of the hadolint ignore by pinning versions for all the
dependencies?
4. Bump the Alpine version for the BUILDER image
5. `make hadolint` only runs on Dockerfile and not the other Dockerfiles
in this repo

cc: @Bidon15

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Dockerfile

@@ -1,9 +1,19 @@
-# stage 1 Generate celestia-appd Binary
-FROM --platform=$BUILDPLATFORM docker.io/golang:1.22.1-alpine3.18 as builder
-
+# This Dockerfile performs a multi-stage build. BUILDER_IMAGE is the image used
+# to compile the celestia-appd binary. RUNTIME_IMAGE is the image that will be
+# returned with the final celestia-appd binary.
+#
+# Separating the builder and runtime image allows the runtime image to be
+# considerably smaller because it doesn't need to have Golang installed.
+ARG BUILDER_IMAGE=docker.io/golang:1.22.1-alpine3.18
+ARG RUNTIME_IMAGE=docker.io/alpine:3.19.1
 ARG TARGETOS
 ARG TARGETARCH
 
+# Stage 1: Build the celestia-appd binary inside a builder image that will be discarded later.
+# Ignore hadolint rule because hadolint can't parse the variable.
+# See https://github.com/hadolint/hadolint/issues/339
+# hadolint ignore=DL3006
+FROM --platform=$BUILDPLATFORM ${BUILDER_IMAGE} AS builder
 ENV CGO_ENABLED=0
 ENV GO111MODULE=on
 # hadolint ignore=DL3018
@@ -20,15 +30,16 @@ RUN uname -a &&\
     CGO_ENABLED=${CGO_ENABLED} GOOS=${TARGETOS} GOARCH=${TARGETARCH} \
     make build
 
-# stage 2
-FROM docker.io/alpine:3.19.1
-
-# Read here why UID 10001: https://github.com/hexops/dockerfile/blob/main/README.md#do-not-use-a-uid-below-10000
+# Stage 2: Create a minimal image to run the celestia-appd binary
+# Ignore hadolint rule because hadolint can't parse the variable.
+# See https://github.com/hadolint/hadolint/issues/339
+# hadolint ignore=DL3006
+FROM ${RUNTIME_IMAGE} AS runtime
+# Use UID 10,001 because UIDs below 10,000 are a security risk.
+# Ref: https://github.com/hexops/dockerfile/blob/main/README.md#do-not-use-a-uid-below-10000
 ARG UID=10001
 ARG USER_NAME=celestia
-
 ENV CELESTIA_HOME=/home/${USER_NAME}
-
 # hadolint ignore=DL3018
 RUN apk update && apk add --no-cache \
     bash \
@@ -40,15 +51,17 @@ RUN apk update && apk add --no-cache \
     -h ${CELESTIA_HOME} \
     -s /sbin/nologin \
     -u ${UID}
-
-# Copy in the binary
+# Copy the celestia-appd binary from the builder into the final image.
 COPY --from=builder /celestia-app/build/celestia-appd /bin/celestia-appd
-
+# Copy the entrypoint script into the final image.
 COPY --chown=${USER_NAME}:${USER_NAME} docker/entrypoint.sh /opt/entrypoint.sh
-
+# Set the user to celestia.
 USER ${USER_NAME}
-
-# p2p, rpc,  prometheus, api and grpc ports
-EXPOSE 26656 26657 26660 1317 9090
-
+# Expose ports:
+# 1317 is the default API server port.
+# 9090 is the default GRPC server port.
+# 26656 is the default node p2p port.
+# 26657 is the default RPC port.
+# 26660 is the port used for Prometheus.
+EXPOSE 1317 9090 26656 26657 26660
 ENTRYPOINT [ "/bin/bash", "/opt/entrypoint.sh" ]

docker/entrypoint.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 
-# This script creates the necessary files before starting Celestia-appd
+# This script creates the necessary files before starting celestia-appd
 
 # only create the priv_validator_state.json if it doesn't exist and the command is start
 if [[ $1 == "start" && ! -f ${CELESTIA_HOME}/data/priv_validator_state.json ]]

go.work.sum

@@ -982,6 +982,8 @@ github.com/prometheus/procfs v0.7.3/go.mod h1:cz+aTbrPOrUb4q7XlbU9ygM+/jj0fzG6c1
 github.com/prometheus/procfs v0.8.0/go.mod h1:z7EfXMXOkbkqb9IINtpCn86r/to3BnA0uaxHdg830/4=
 github.com/protolambda/bls12-381-util v0.0.0-20220416220906-d8552aa452c7/go.mod h1:IToEjHuttnUzwZI5KBSM/LOOW3qLbbrHOEfp3SbECGY=
 github.com/prysmaticlabs/gohashtree v0.0.1-alpha.0.20220714111606-acbb2962fb48/go.mod h1:4pWaT30XoEx1j8KNJf3TV+E3mQkaufn7mf+jRNb/Fuk=
+github.com/pyroscope-io/client v0.7.2/go.mod h1:FEocnjn+Ngzxy6EtU9ZxXWRvQ0+pffkrBxHLnPpxwi8=
+github.com/pyroscope-io/godeltaprof v0.1.2/go.mod h1:psMITXp90+8pFenXkKIpNhrfmI9saQnPbba27VIaiQE=
 github.com/pyroscope-io/client v0.7.2 h1:OX2qdUQsS8RSkn/3C8isD7f/P0YiZQlRbAlecAaj/R8=
 github.com/pyroscope-io/client v0.7.2/go.mod h1:FEocnjn+Ngzxy6EtU9ZxXWRvQ0+pffkrBxHLnPpxwi8=
 github.com/pyroscope-io/godeltaprof v0.1.2 h1:MdlEmYELd5w+lvIzmZvXGNMVzW2Qc9jDMuJaPOR75g4=