Update template to easier instructions

Author: Tom-Notch

.dockerignore

@@ -0,0 +1,8 @@
+# Applies to build only, ignore everything by default
+**
+
+# Keep only files needed for build
+!environment.yml
+!pyproject.toml
+!docker/
+!docker-compose.yml

.env

@@ -4,13 +4,20 @@ XAUTH=/tmp/.docker.xauth
 AVAILABLE_CORES=$(($(nproc) - 1))
 
 DOCKER_USER=todo-docker-user
+BASE_IMAGE=todo-base-image
 IMAGE_NAME=todo-image-name
+IMAGE_USER=todo-image-user
 IMAGE_TAG=latest
+TIME_ZONE=$(cat /etc/timezone 2>/dev/null || readlink /etc/localtime | sed 's|.*/zoneinfo/||')
+TIME_ZONE=${TIME_ZONE:-UTC}
 
 CONTAINER_NAME=${IMAGE_NAME}
-CONTAINER_HOME_FOLDER=/root
+HOME_FOLDER=/home/${IMAGE_USER}
 CODE_FOLDER=${IMAGE_NAME}
 
 HOST_UID=$(id -u)
 HOST_GID=$(id -g)
-HOSTNAME=${HOSTNAME}
+HOST=${HOST:-$(hostname)}
+HOSTNAME=${HOSTNAME:-$(hostname)}
+
+BUILDER=multi-platform

README.md

@@ -8,7 +8,9 @@
 
 ## Usage Guidelines
 
-### Base Repo
+TLDR: Search for `todo` and update all occurrences to your desired name
+
+### Base Repository
 
 1. Change [LICENSE](LICENSE) if necessary
 
@@ -18,19 +20,37 @@
 
 ### Docker Config
 
-1. Modify **DOCKER_USER**, **IMAGE_NAME** in [.env](.env)
+1. Modify `todo-docker-user`, `todo-base-image`, `todo-image-name`, `todo-image-user` in [.env](.env)
+
+   - [.env](.env) will be loaded when you use docker compose for build/run/push
+   - `todo-docker-user` refers to your docker hub account username
+   - `todo-base-image` is the image dockerfile is based on, such as `nvidia/cuda:13.0.0-cudnn-devel-ubuntu24.04`
+   - `todo-image-user` refers to the default user inside the image, which is used to determine home folder
 
-1. Modify the service name from **default** to your service name in [docker-compose.yml](docker-compose.yml)
+1. Modify the service name from `todo-service-name` to your service name in [docker-compose.yml](docker-compose.yml), add additional volume mounting options such as dataset directories
 
-1. Update [Dockerfile](docker/latest/Dockerfile)
+1. Update [Dockerfile](docker/latest/Dockerfile) and [.dockerignore](.dockerignore)
+
+   - Existing dockerfile has screen & tmux config, oh-my-zsh, cmake, and other basic goodies
+   - Add any additional dependency installations at appropriate locations
 
 1. [build.sh](scripts/build.sh) to build and test the image locally in your machine's architecture
 
-1. [push.sh](scripts/push.sh) to push the multi-arch image to the registry
+   - The scripts uses buildx to build multi-arch image, you can disable this by removing redundant archs in [docker-compose.yml](docker-compose.yml)
+   - Building stage does not have GPU access, if some of your dependencies need GPU, build them inside a running container and commit to the final image
+
+1. [run_container.sh](scripts/run_container.sh) or `docker compose up -d` to run and test a built image
+
+   - The service by default will mount the whole repository onto `CODE_FOLDER` inside the container so any modification inside also takes effect outside, which is useful when you use vscode remote extension to develop inside a running container with remote docker context
+   - You should be able to run and see GUI applications inside the container if `DISPLAY` is set correctly when you run the script
+
+1. [push.sh](scripts/push.sh) to push the multi-arch image to docker hub
+
+   - You should have the docker hub repository set up before pushing
 
 ## Developer Quick Start
 
-- Run [scripts/dev-setup.sh](scripts/dev-setup.sh) to setup the development environment
+- Run [scripts/dev_setup.sh](scripts/dev_setup.sh) to setup the development environment
 
 ## Note
 

docker-compose.yml

@@ -1,7 +1,5 @@
-version: "3"
-
 services:
-    default:
+    todo-service-name:
         build:
             dockerfile: ./docker/${IMAGE_TAG}/Dockerfile
             x-bake:
@@ -17,7 +15,8 @@ services:
         pull_policy: missing
         container_name: ${CONTAINER_NAME}
         privileged: true
-        hostname: ${HOSTNAME}
+        user: root
+        hostname: ${HOST}
         network_mode: host
         ipc: host
         pid: host
@@ -34,8 +33,8 @@ services:
             - /var/lib/systemd/coredump/:/cores
             - /tmp/.X11-unix/:/tmp/.X11-unix/:rw
             - ${XAUTH}:${XAUTH}
-            - .:${CONTAINER_HOME_FOLDER}/${CODE_FOLDER}
-        working_dir: ${CONTAINER_HOME_FOLDER}/${CODE_FOLDER}
+            - .:${HOME_FOLDER}/${CODE_FOLDER}
+        working_dir: ${HOME_FOLDER}/${CODE_FOLDER}
         stdin_open: true # for -it
         tty: true # for -it
         # command: /bin/zsh

docker/latest/Dockerfile

@@ -1,68 +1,137 @@
 # Do not add --platform=linux/blabla since this is intended for multiplatform builds
-FROM tomnotch/bipvrobotics-base-image:latest
-ENV HOME_FOLDER=/root
-WORKDIR $HOME_FOLDER/
+FROM ${BASE_IMAGE}
+ENV HOME=${HOME_FOLDER}
+WORKDIR ${HOME_FOLDER}/
+
+# Make home folder if not exists
+RUN mkdir -p ${HOME_FOLDER}
 
 # Fix apt install stuck problem
 ENV DEBIAN_FRONTEND=noninteractive
 RUN echo 'debconf debconf/frontend select Noninteractive' | debconf-set-selections
 
+# Copy home folder config
+COPY --from=home-folder-config . ${HOME_FOLDER}/
+
 # update all obsolete packages to latest, install sudo, and cleanup
 RUN apt update -o Acquire::Check-Valid-Until=false -o Acquire::AllowInsecureRepositories=true -o Acquire::AllowDowngradeToInsecureRepositories=true && \
     apt full-upgrade -y && \
     apt install -y sudo ca-certificates && \
     apt autoremove -y && \
     apt autoclean -y
 
+# fix local time problem
+RUN apt-get install -y --no-install-recommends tzdata && \
+    ln -fs /usr/share/zoneinfo/${TIME_ZONE} /etc/localtime && \
+    echo "${TIME_ZONE}" > /etc/timezone && \
+    dpkg-reconfigure --frontend noninteractive tzdata
+
+# update all obsolete packages to latest, install sudo, and cleanup
+RUN apt update -o Acquire::Check-Valid-Until=false -o Acquire::AllowInsecureRepositories=true -o Acquire::AllowDowngradeToInsecureRepositories=true && \
+    apt full-upgrade -y && \
+    apt install -y sudo ca-certificates && \
+    apt autoremove -y && \
+    apt autoclean -y
+
+# Install some goodies
+RUN apt-get install -y --no-install-recommends \
+    build-essential \
+    clang-format \
+    curl \
+    dirmngr \
+    git \
+    gnupg \
+    htop \
+    less \
+    locate \
+    lsb-release \
+    nano \
+    ncdu \
+    net-tools \
+    perl \
+    screen \
+    software-properties-common \
+    tmux \
+    tmuxp \
+    tree \
+    unzip \
+    valgrind \
+    vim \
+    wget \
+    zsh
+
+# upgrade cmake to kitware official apt-get repo release version
+RUN wget https://apt-get.kitware.com/kitware-archive.sh -O- | sh -s && \
+    apt-get upgrade -y cmake && \
+    apt-get autoremove -y
+
 # # Add a new group and user
-# RUN addgroup --gid 1000 $USER && \
-#     adduser --uid 1000 --ingroup $USER --home $HOME_FOLDER --shell /bin/zsh --disabled-password --gecos "" $USER && \
-#     echo "$USER ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
+# RUN addgroup --gid 1000 $IMAGE_USER && \
+#     adduser --uid 1000 --ingroup $IMAGE_USER --home ${HOME_FOLDER} --shell /bin/zsh --disabled-password --gecos "" $IMAGE_USER && \
+#     echo "$IMAGE_USER ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
 # # Fix UID/GID when mounting from host using this: https://github.com/boxboat/fixuid
 # RUN curl -SsL https://github.com/boxboat/fixuid/releases/download/v0.6.0/fixuid-0.6.0-linux-amd64.tar.gz | tar -C /usr/local/bin -xzf - && \
 #     chown root:root /usr/local/bin/fixuid && \
 #     chmod 4755 /usr/local/bin/fixuid && \
 #     mkdir -p /etc/fixuid
 
-# # Switch to the new user
-# USER $USER:$USER
-
-#! Install OpenCV 4.2.0 with QUIRC support from source
-ENV OPENCV_VERSION=4.2.0
-RUN pip3 uninstall -y opencv && \
-    apt install -y --no-install-recommends libavcodec-dev libavformat-dev libswscale-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev libgtk-3-dev libpng-dev libjpeg-dev && \
-    git clone --depth 1 --recursive https://github.com/opencv/opencv.git $HOME_FOLDER/opencv -b $OPENCV_VERSION && \
-    #  follow the error information，replace all the “ipcp-unit-growth” with “ipa-cp-unit-growth” in 3rdparty/carotene/CMakeLists.txt and 3rdparty/carotene/hal/CMakeLists.txt
-    perl -pi -e 's/ipcp-unit-growth/ipa-cp-unit-growth/g' $HOME_FOLDER/opencv/3rdparty/carotene/CMakeLists.txt $HOME_FOLDER/opencv/3rdparty/carotene/hal/CMakeLists.txt && \
-    git clone --depth 1 --recursive https://github.com/opencv/opencv_contrib.git $HOME_FOLDER/opencv_contrib -b $OPENCV_VERSION && \
-    mkdir -p $HOME_FOLDER/opencv/build && \
-    cd $HOME_FOLDER/opencv/build && \
-    cmake \
-    -D CMAKE_CXX_STANDARD=20 \
-    -D EIGEN_INCLUDE_PATH=/usr/include/eigen3 \
-    -D OPENCV_GENERATE_PKGCONFIG=ON \
-    -D BUILD_opencv_python3=ON \
-    -D OPENCV_PYTHON3_INSTALL_PATH=/usr/local/lib/python3.8/dist-packages \
-    # -D OPENCV_ENABLE_NONFREE=ON \
-    -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
-    # -D WITH_LAPACK=ON \
-    -D WITH_GTK=ON \
-    -D WITH_TBB=ON \
-    # -D WITH_QUIRC=ON \
-    -D WITH_GSTREAMER=ON \
-    -D WITH_V4L=ON \
-    # -D WITH_OPENGL=ON \
-    -D BUILD_TESTS=OFF \
-    -D BUILD_PERF_TESTS=OFF \
-    -D BUILD_EXAMPLES=OFF \
-    -D CMAKE_BUILD_TYPE=RELEASE \
-    -D CMAKE_INSTALL_PREFIX=/usr/local .. && \
-    make install -j$(($(nproc)-1)) && \
-    echo "export OpenCV_DIR=/usr/local/lib/cmake/opencv4/" >> ${HOME_FOLDER}/.zshrc && \
-    echo "export OpenCV_DIR=/usr/local/lib/cmake/opencv4/" >> ${HOME_FOLDER}/.bashrc && \
-    rm -rf $HOME_FOLDER/opencv && \
-    rm -rf $HOME_FOLDER/opencv_contrib
+# install zsh, Oh-My-Zsh, and plugins
+RUN sh -c "$(wget -O- https://github.com/deluan/zsh-in-docker/releases/latest/download/zsh-in-docker.sh)" -- \
+    -t https://github.com/romkatv/powerlevel10k \
+    -p git \
+    -p https://github.com/zsh-users/zsh-autosuggestions \
+    -p https://github.com/zsh-users/zsh-completions \
+    -p https://github.com/zsh-users/zsh-syntax-highlighting \
+    -a "[[ ! -f ${HOME_FOLDER}/.p10k.zsh ]] || source ${HOME_FOLDER}/.p10k.zsh" \
+    -a "POWERLEVEL9K_DISABLE_GITSTATUS=true" \
+    -a "bindkey -M emacs '^[[3;5~' kill-word" \
+    -a "bindkey '^H' backward-kill-word" \
+    -a "autoload -U compinit && compinit" \
+    -a "export PATH=~/.local/bin:${PATH}"
+
+# change default shell for the ${IMAGE_USER} in the image building process for extra environment safety
+RUN chsh -s $(which zsh)
+
+#! Examples of actual dependency install:
+# #! Install OpenCV 4.2.0 with QUIRC support from source
+# ENV OPENCV_VERSION=4.2.0
+# RUN pip3 uninstall -y opencv && \
+#     apt install -y --no-install-recommends libavcodec-dev libavformat-dev libswscale-dev libgstreamer-plugins-base1.0-dev libgstreamer1.0-dev libgtk-3-dev libpng-dev libjpeg-dev && \
+#     git clone --depth 1 --recursive https://github.com/opencv/opencv.git ${HOME_FOLDER}/opencv -b $OPENCV_VERSION && \
+#     #  follow the error information，replace all the “ipcp-unit-growth” with “ipa-cp-unit-growth” in 3rdparty/carotene/CMakeLists.txt and 3rdparty/carotene/hal/CMakeLists.txt
+#     perl -pi -e 's/ipcp-unit-growth/ipa-cp-unit-growth/g' ${HOME_FOLDER}/opencv/3rdparty/carotene/CMakeLists.txt ${HOME_FOLDER}/opencv/3rdparty/carotene/hal/CMakeLists.txt && \
+#     git clone --depth 1 --recursive https://github.com/opencv/opencv_contrib.git ${HOME_FOLDER}/opencv_contrib -b $OPENCV_VERSION && \
+#     mkdir -p ${HOME_FOLDER}/opencv/build && \
+#     cd ${HOME_FOLDER}/opencv/build && \
+#     cmake \
+#     -D CMAKE_CXX_STANDARD=20 \
+#     -D EIGEN_INCLUDE_PATH=/usr/include/eigen3 \
+#     -D OPENCV_GENERATE_PKGCONFIG=ON \
+#     -D BUILD_opencv_python3=ON \
+#     -D OPENCV_PYTHON3_INSTALL_PATH=/usr/local/lib/python3.8/dist-packages \
+#     # -D OPENCV_ENABLE_NONFREE=ON \
+#     -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
+#     # -D WITH_LAPACK=ON \
+#     -D WITH_GTK=ON \
+#     -D WITH_TBB=ON \
+#     # -D WITH_QUIRC=ON \
+#     -D WITH_GSTREAMER=ON \
+#     -D WITH_V4L=ON \
+#     # -D WITH_OPENGL=ON \
+#     -D BUILD_TESTS=OFF \
+#     -D BUILD_PERF_TESTS=OFF \
+#     -D BUILD_EXAMPLES=OFF \
+#     -D CMAKE_BUILD_TYPE=RELEASE \
+#     -D CMAKE_INSTALL_PREFIX=/usr/local .. && \
+#     make install -j$(($(nproc)-1)) && \
+#     echo "export OpenCV_DIR=/usr/local/lib/cmake/opencv4/" >> ${HOME_FOLDER}/.zshrc && \
+#     echo "export OpenCV_DIR=/usr/local/lib/cmake/opencv4/" >> ${HOME_FOLDER}/.bashrc && \
+#     rm -rf ${HOME_FOLDER}/opencv && \
+#     rm -rf ${HOME_FOLDER}/opencv_contrib
+
+# Add git safe directory
+RUN git config --global --add safe.directory "*"
 
 # end of sudo apt installs
 RUN apt full-upgrade -y && \
@@ -71,11 +140,17 @@ RUN apt full-upgrade -y && \
     apt clean -y && \
     rm -rf /var/lib/apt/lists/*
 
+# change owner of home folder
+RUN chown -R ${IMAGE_USER}:${IMAGE_USER} ${HOME_FOLDER}
+
+# change user
+USER ${IMAGE_USER}
+
 # Set the default shell to zsh
 SHELL [ "/bin/zsh", "-c" ]
 
 # # move fixuid config
-# RUN mv $HOME_FOLDER/fixuid-config.yml /etc/fixuid/config.yml
+# RUN mv ${HOME_FOLDER}/fixuid-config.yml /etc/fixuid/config.yml
 
 # Entrypoint command
 # ENTRYPOINT [ "/bin/sh" , "-c", "fixuid; /bin/zsh" ]

scripts/build.sh

@@ -8,7 +8,33 @@
 # Copyright Ⓒ 2024 Mukai (Tom Notch) Yu
 #
 
+set -euo pipefail
+
+before_env="$(mktemp)"
+after_env="$(mktemp)"
+tmp_dockerfile="$(mktemp)"
+cleanup() { rm -f "${before_env}" "${after_env}" "${tmp_dockerfile}"; }
+trap cleanup EXIT
+
+env | sort >"${before_env}"
+
+set -a
 . "$(dirname "$0")"/variables.sh
+set +a
+
+env | sort >"${after_env}"
+
+diff_env="$(
+	awk -F= '
+    NR==FNR { before[$1]=$0; next }
+    {
+      name=$1
+      if (!(name in before) || before[name] != $0)
+        printf " ${%s}", name
+    }
+  ' "${before_env}" "${after_env}"
+)"
+diff_env="${diff_env# }" # trim leading space
 
 # Determine the local platform
 if [[ "$(uname -m)" == "x86_64" ]]; then
@@ -20,19 +46,25 @@ else
 	exit 1
 fi
 
-# Desired builder name
-BUILDER_NAME="multi-platform"
-
 # Check if the builder already exists
-if ! docker buildx ls | grep -q "^${BUILDER_NAME} "; then
-	echo "Creating Docker Buildx builder '${BUILDER_NAME}'..."
+if ! docker buildx inspect "${BUILDER}" &>/dev/null; then
+	echo "Creating Docker Buildx builder '${BUILDER}'..."
 	docker buildx create \
-		--name "${BUILDER_NAME}" \
+		--name "${BUILDER}" \
 		--use --platform linux/amd64,linux/arm64 \
 		--driver docker-container
 else
-	echo "Docker Buildx builder '${BUILDER_NAME}' already exists."
+	echo "Docker Buildx builder '${BUILDER}' already exists."
+	docker buildx use "${BUILDER}"
 fi
 
+# environment variable substitution trick
+envsubst "${diff_env}" <"$(dirname "$0")/../docker/${IMAGE_TAG}/Dockerfile" >"${tmp_dockerfile}"
+
+echo ">>> Substituted dockerfile:"
+echo "----------------------------------------"
+cat "${tmp_dockerfile}"
+echo "----------------------------------------"
+
 # Build the Docker image for only the local platform, push.sh will push multi-platform version
-docker buildx bake --file "$(dirname "$0")"/../docker-compose.yml --load --set "*.platform=$LOCAL_PLATFORM"
+docker buildx bake --file "$(dirname "$0")"/../docker-compose.yml --load --set "*.platform=${LOCAL_PLATFORM}" --set "*.dockerfile=${tmp_dockerfile}"

scripts/dev-setup.sh scripts/dev_setup.shscripts/dev-setup.sh renamed to scripts/dev_setup.sh

@@ -10,6 +10,6 @@
 
 . "$(dirname "$0")"/variables.sh
 
-docker exec --privileged -it "$CONTAINER_NAME" pkill -f zsh
+docker exec --privileged -it "${CONTAINER_NAME}" pkill -f zsh
 
-docker rm -f "$CONTAINER_NAME"
+docker rm -f "${CONTAINER_NAME}"

scripts/kill.sh

@@ -10,4 +10,4 @@
 
 . "$(dirname "$0")"/variables.sh
 
-docker pull "$DOCKER_USER"/"$IMAGE_NAME":"$IMAGE_TAG"
+docker pull "${DOCKER_USER}"/"${IMAGE_NAME}":"${IMAGE_TAG}"