Improvements for docker user management and documentation

docker/README.md

@@ -181,14 +181,16 @@ As mentioned above, the docker images are built with a `UID:GID`
 dervied from account used to build the images. If you would prefer to
 use a different identity, the `--user` switch to the `docker run`
 command will override the builtin identities. This can be especially
-useful if the images are stored in a repository.
+useful if the images are stored in a registry.
 
+<!---
 ** NOTE: ** We need a better way to process registrations for SGX HW mode. In
 theory, the best way to do this may be to create a canonical base
 services image; populate an instance of it with CCF private keys, run
 the registration. That way the canonical base service image would have
 a standard version of the enclave library that would not have to deal
 with reproducible builds.
+--->
 
 ### CCF Deployment ###
 
@@ -305,3 +307,74 @@ For example:
 ```bash
     user@has:/project/pdo# source /project/pdo/tools/start_client.sh --ledger http://127.0.0.1:6600/
 ```
+
+<!--- xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx --->
+## Pattern: Deploy PDO Images Through a Registry ##
+
+Deploying PDO images through a Docker registry additionally requires
+creation of an account used to run the PDO services. Since services
+are configured through a shared host file system (the `xfer` directory
+tree) permissions must be set appropriately.
+
+### Build the Images ###
+
+PDO images that will be pushed to a shared registry should be built
+with a unique user identity that is unlikely to exist on the servers
+where it will be deployed. The UID that is used by default when
+building the images in the GitHub registry is 55172. The following
+statement will build PDO images with that UID.
+
+```bash
+make PDO_USER_UID=55172 PDO_GROUP_UID=55172
+```
+
+Once built, use the standard docker commands to push the images to
+your registry. If you wish to do PDO service development, you will
+need access to all of the images (`pdo_base`, `pdo_services_base`,
+`pdo_services`, `pdo_client`, `pdo_ccf_base`, and `pdo_ccf`). For
+using and developing contracts the only necessary images are
+`pdo_services`, `pdo_client` and `pdo_ccf`.
+
+*Note*: prebuilt images are often available from the GitHub container
+registry through
+[Hyperledger Labs](https://github.com/orgs/hyperledger-labs/packages?q=pdo).
+These images can be pulled using standard docker commands such as:
+
+```bash
+docker pull ghcr.io/hyperledger-labs/pdo_client:latest
+docker pull ghcr.io/hyperledger-labs/pdo_services:latest
+docker pull ghcr.io/hyperledger-labs/pdo_ccf:latest
+```
+
+### Create Accounts ###
+
+To manage local storage associated with the containers (specifically
+the contents of the `xfer` directory), create a local user/group
+account that corresponds to the UIDs used in the PDO images. The
+following commands create a `pdo_user` user and group with UIDs that
+correspond to the ones used above (and consistent with the identities
+used in the images in GHCR:
+
+```bash
+sudo addgroup --gid 55172 pdo_user
+sudo adduser --uid 55172 --gid 55172 --disabled-login --no-create-home pdo_user
+```
+
+Next, add the local user that will be used to manage the containers to
+the `pdo_user` group.
+
+```bash
+sudo adduser <username> pdo_user
+```
+
+And, finally, change the `xfer` directory ownership and permissions to
+give group users write permission.
+
+```bash
+sudo chown -R pdo_user:pdo_user xfer
+sudo chmod -R g+w xfer
+```
+
+At this point, you should be able to use the instructions above for
+[Service Deployment](#pattern:-service-deployment) using the PDO
+images.

docker/base.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 # ------------------------------------------------------------------------------
 
-version: "3.4"
+
 
 services:
   base_container:

docker/ccf_base.yaml

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ------------------------------------------------------------------------------
-version: "3.4"
+
 
 services:
   ccf_container:

docker/client_base.yaml

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ------------------------------------------------------------------------------
-version: "3.4"
+
 
 services:
   client_container:

docker/configured_services.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 # ------------------------------------------------------------------------------
 
-version: "3.4"
+
 
 services:
   services_container:

docker/pdo_base.dockerfile

@@ -25,8 +25,10 @@ ENV TERM=screen-256color
 # -----------------------------------------------------------------
 ARG ADD_APT_PKGS=
 
-ENV DEBIAN_FRONTEND "noninteractive"
-RUN apt-get update \
+ENV DEBIAN_FRONTEND="noninteractive"
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update \
     && apt-get install -y -q --no-install-recommends \
         autoconf \
         automake \
@@ -77,5 +79,23 @@ RUN wget -q https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-$
     && dpkg --install ${WASI_PACKAGE} \
     && rm ${WASI_PACKAGE}
 
+# -----------------------------------------------------------------
+# Create the pdo_user account and group that will be used for
+# future installations into the pdo install directory
+# -----------------------------------------------------------------
+ARG UNAME=pdo_user
+ENV UNAME=${UNAME}
+
+ARG UID=1000
+ARG GID=$UID
+
+RUN groupadd -f -g $GID -o $UNAME
+RUN useradd -m -u $UID -g $GID -d /project/pdo -o -s /bin/bash $UNAME
+
+# -----------------------------------------------------------------
+# Prep for the installation
+# -----------------------------------------------------------------
+USER $UNAME
+
 WORKDIR /project/pdo/tools
 COPY tools/environment.sh ./

docker/pdo_ccf.dockerfile

@@ -19,7 +19,7 @@
 # to cache pip downloads between builds, cutting down noticeably build time.
 # Note that cache is cleaned with the "uusal" docker prune commans, e.g., docker builder prune.
 
-ARG PDO_VERSION
+ARG PDO_VERSION=latest
 FROM pdo_ccf_base:${PDO_VERSION}
 
 # -----------------------------------------------------------------
@@ -38,6 +38,13 @@ ENV PDO_DEBUG_BUILD=${PDO_DEBUG_BUILD}
 ARG XFER_DIR=/project/pdo/xfer
 ENV XFER_DIR=${XFER_DIR}
 
+# copy the source files into the image using the user
+# identity that was created in the base container
+ARG UNAME=pdo_user
+ENV UNAME=${UNAME}
+
+USER $UNAME
+
 # copy the source files into the image
 WORKDIR /project/pdo
 COPY --chown=${UNAME}:${UNAME} repository /project/pdo/src
@@ -49,9 +56,7 @@ WORKDIR /project/pdo/tools
 COPY --chown=${UNAME}:${UNAME} tools/*.sh ./
 
 # build it!!!
-ARG UID=1000
-ARG GID=${UID}
-RUN --mount=type=cache,uid=${UID},gid=${GID},target=/project/pdo/.cache/pip \
+RUN --mount=type=cache,target=/project/pdo/.cache/pip \
     /project/pdo/tools/build_ccf.sh
 
 # Network ports for running services

docker/pdo_ccf_base.dockerfile

@@ -24,13 +24,17 @@ ARG UBUNTU_NAME=focal
 
 ENV TERM=screen-256color
 
+USER root
+
 # -----------------------------------------------------------------
 # Install base packages
 # -----------------------------------------------------------------
 ARG ADD_APT_PKGS=
 
-ENV DEBIAN_FRONTEND "noninteractive"
-RUN apt-get update \
+ENV DEBIAN_FRONTEND="noninteractive"
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update \
     && apt-get install -y -q --no-install-recommends \
         libsecp256k1-dev \
         lsof \
@@ -46,8 +50,9 @@ RUN apt-get update \
 RUN echo "deb [arch=amd64] https://download.01.org/intel-sgx/sgx_repo/ubuntu ${UBUNTU_NAME} main" >> /etc/apt/sources.list
 RUN curl https://download.01.org/intel-sgx/sgx_repo/ubuntu/intel-sgx-deb.key | apt-key add -
 
-
-RUN apt-get update \
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update \
     && apt-get install -y --no-install-recommends \
         sgx-aesm-service \
         libsgx-dcap-ql \
@@ -59,19 +64,20 @@ RUN apt-get clean \
     && rm -rf /var/lib/apt/lists/*
 
 # -----------------------------------------------------------------
+# Create the pdo_user account and group that will be used for
+# future installations into the pdo install directory
 # -----------------------------------------------------------------
-WORKDIR /project/pdo
-
-ARG UNAME=pdo_ccf
+ARG UNAME=pdo_user
 ENV UNAME=${UNAME}
 
 ARG UID=1000
 ARG GID=$UID
 
-RUN echo $UID $GID
 RUN groupadd -f -g $GID -o $UNAME
 RUN useradd -m -u $UID -g $GID -d /project/pdo -o -s /bin/bash $UNAME
-RUN chown --recursive $UNAME:$UNAME /project/pdo
+
+# -----------------------------------------------------------------
 USER $UNAME
 
+WORKDIR /project/pdo
 ENTRYPOINT ["/bin/bash"]

docker/pdo_client.dockerfile

@@ -19,24 +19,9 @@
 # to cache pip downloads between builds, cutting down noticeably build time.
 # Note that cache is cleaned with the "uusal" docker prune commans, e.g., docker builder prune.
 
-ARG PDO_VERSION
+ARG PDO_VERSION=latest
 FROM pdo_base:${PDO_VERSION}
 
-# -----------------------------------------------------------------
-# -----------------------------------------------------------------
-WORKDIR /project/pdo
-
-ARG UNAME=pdo_client
-ENV UNAME=${UNAME}
-
-ARG UID=1000
-ARG GID=${UID}
-
-RUN groupadd -f -g $GID -o $UNAME
-RUN useradd -m -u $UID -g $GID -d /project/pdo -o -s /bin/bash $UNAME
-RUN chown --recursive $UNAME:$UNAME /project/pdo
-USER $UNAME
-
 # -----------------------------------------------------------------
 # set up the PDO sources
 # -----------------------------------------------------------------
@@ -54,6 +39,16 @@ ENV PDO_INTERPRETER=${PDO_INTERPRETER}
 ARG PDO_LOG_LEVEL=info
 ENV PDO_LOG_LEVEL=${PDO_LOG_LEVEL}
 
+# -----------------------------------------------------------------
+# use the identity created in the base container
+# -----------------------------------------------------------------
+ARG UNAME=pdo_user
+ENV UNAME=${UNAME}
+
+USER $UNAME
+
+# -----------------------------------------------------------------
+# -----------------------------------------------------------------
 # copy the source files into the image
 WORKDIR /project/pdo
 COPY --chown=${UNAME}:${UNAME} repository /project/pdo/src
@@ -65,8 +60,9 @@ WORKDIR /project/pdo/tools
 COPY --chown=${UNAME}:${UNAME} tools/*.sh ./
 
 # build it!!!
-RUN --mount=type=cache,uid=${UID},gid=${GID},target=/project/pdo/.cache/pip \
+RUN --mount=type=cache,target=/project/pdo/.cache/pip \
     /project/pdo/tools/build_client.sh
 
-RUN ln -s /project/pdo/tools/bashrc_client.sh /project/pdo/.bashrc
+RUN rm -f /project/pdo/.bashrc; ln -s /project/pdo/tools/bashrc_client.sh /project/pdo/.bashrc
+
 ENTRYPOINT [ "/bin/bash" ]

docker/pdo_services.dockerfile

@@ -19,7 +19,7 @@
 # to cache pip downloads between builds, cutting down noticeably build time.
 # Note that cache is cleaned with the "uusal" docker prune commans, e.g., docker builder prune.
 
-ARG PDO_VERSION
+ARG PDO_VERSION=latest
 FROM pdo_services_base:${PDO_VERSION}
 
 # -----------------------------------------------------------------
@@ -28,7 +28,7 @@ FROM pdo_services_base:${PDO_VERSION}
 ARG REBUILD=0
 
 ARG SGX_MODE=SIM
-ENV SGX_MODE $SGX_MODE
+ENV SGX_MODE=$SGX_MODE
 
 ARG PDO_DEBUG_BUILD=1
 ENV PDO_DEBUG_BUILD=${PDO_DEBUG_BUILD}
@@ -45,7 +45,12 @@ ENV PDO_MEMORY_CONFIG=${PDO_MEMORY_CONFIG}
 ARG PDO_LOG_LEVEL=info
 ENV PDO_LOG_LEVEL=${PDO_LOG_LEVEL}
 
-# copy the source files into the image
+# copy the source files into the image using the user
+# identity that was created in the base container
+ARG UNAME=pdo_user
+ENV UNAME=${UNAME}
+
+USER $UNAME
 WORKDIR /project/pdo
 COPY --chown=${UNAME}:${UNAME} repository /project/pdo/src
 
@@ -55,18 +60,15 @@ COPY --chown=${UNAME}:${UNAME} repository /project/pdo/src
 WORKDIR /project/pdo/tools
 COPY --chown=${UNAME}:${UNAME} tools/*.sh ./
 
-# built it!
-ARG UID=1000
-ARG GID=${UID}
-RUN --mount=type=cache,uid=${UID},gid=${GID},target=/project/pdo/.cache/pip \
+# build it!
+RUN --mount=type=cache,target=/project/pdo/.cache/pip \
     /project/pdo/tools/build_services.sh
 
 # Network ports for running services
 EXPOSE 7001 7002 7003 7004 7005
 EXPOSE 7101 7102 7103 7104 7105
 EXPOSE 7201 7202 7203 7204 7205
 
-
 # Note that the entry point when specified with exec syntax
 # can be extended through the docker run interface far more
 # easily than if you use the other specification format of