Files
TSYSDevStack/build.sh
ReachableCEO 544d1c31e5 Toolboxes-Docs (vibe-kanban c5c3e68d)
TSYS Group Development Stack - Toolboxes - DocsAndDiagrams - Product Requirements Document -

## Docker Image Boilerplate

Image name: tsysdevstack-toolboxes-docs
Image username: tsysdevstack
Image base: latest Debian stable

- ALL operations MUST be as the tsysdevstack user
- NO ROOT ACCESS should be possible at runtime (no sudo, no su)
- The ONLY permitted use of root is during build time, and that MUST be to the ABSOLUTE MINIMUM extent possible (just for apt-get operations and creating the tsysdevstack user). Switching to tsysdevstack as early as possible.
- mise (as the tsysdevstack user) MUST be used to install all language runtimes (node/python/rust/ruby).
- If an application is installed via npm/pip/cargo/gem, those application installs MUST be done via mise managed versions of npm/pip/cargo/gem.
- NO system wide (apt-get) installs of language runtimes are allowed
- This is a production container. Use ALL best common practices for the building and securing of docker containers. (Buildx, multi stage, hardened )
- Use yamllint/hadolint/shellcheck (available via docker images on this system) as a QA gate BEFORE attempting to build the image. If ANY changes to Dockerfile/run.sh/build.sh/test.sh are made, run them through hadolint/shellcheck respectively.
- ALL hadolint/yamllint/shellcheck issues MUST be FULLY RESOLVED always. The only acceptable QA outcome is when those tools return no warnings/errors.
- Think about how to efficiently create the Dockerfile, keeping caching of layers in mind , especially how layers can be cached across multiple different image builds.
- Utilize buildkit/buildx
- This container needs to run on PC/Raspberry Pi/Mac M series.
- Reproducibility of the build is PARAMOUNT! Use version pinning for EVERYTHING. Do the research to find the latest stable version and update Dockerfile and other files accordingly. Do not "just use latest", that is never acceptable. You MUST pin the Debian package versions, and any of the tooling you install via mise managed runtimes.
- Use the examples subdirectory and create example artifacts and workflow scripts to fully QA the functionality of the container
- Create a README.md file that is BEAUTIFULLY formatted (using table of contents/headers/icons/graphics/whitespace/tables (with left justified text)). Document the container image thoroughly.
- Use the documentation subdirectory and creaate the following artifacts:
  - TROUBLESHOOTING.md
  - CHEATSHEET.md
  - USAGE.md
- Use the output subdirectory and create the following artifacts (ensure they will pass strict QA testing/auditing):

- Dockerfile
- docker-compose.yml
- devcontainer.json
- run.sh
- build.sh
- test.sh

## Docker Image Requirements

The overall purpose of this container image is to be a document production workhorse.

Core workflows:

- pandoc

 markdown to pdf/doc (for resumes) (so simple formatting, ATS optimized)
 markdown to pdf (for project plans, budgets, proposals etc)
 Joplin markdown notes to PDF preserving all the extensive formatting that Joplin has when it renders the notes to pdf

The generated PDFs need to be beautiful. Rich fonts, graphics, formatting of the code listings etc. We will be heavily leaning into texlive/xetex for this. I would also like to explore using wkhtmltopdf so that CSS can be used to style the output.

- mdbook
- typst
- marp
- markwhen
- kroki cli
- quarto
- bibtool
- vale

Add in any other common support tools you think may be needed (such as jq/yq).

Generally this image will be used "headless" to run a generation workflow (or mdbook serve during active development of an mdbook site).

It should have fish as it's shell (and also bash/zsh) for the occasional interactive use.

Follow test-driven-development for this project without fail.

Ensure that the image is built successfully and fully validated against this PRD

Use the /home/localuser/TSYSDevStack/Toolbox/docs/output directory for all of the work you do for this task.
2025-11-11 20:59:13 -06:00

193 lines
5.0 KiB
Bash
Executable File

#!/usr/bin/env bash
# build.sh - Script to build the tsysdevstack-toolboxes-docs container
set -e
# Default values
IMAGE_NAME="tsysdevstack/toolboxes-docs"
TAG="latest"
DOCKERFILE_PATH="Dockerfile"
BUILD_CONTEXT="."
PLATFORMS="linux/amd64,linux/arm64"
# Parse command line arguments
NO_CACHE=false
QUIET=false
SKIP_TESTS=false
while [[ $# -gt 0 ]]; do
case $1 in
--no-cache)
NO_CACHE=true
shift
;;
--quiet)
QUIET=true
shift
;;
--skip-tests)
SKIP_TESTS=true
shift
;;
--platforms)
PLATFORMS="$2"
shift 2
;;
-t|--tag)
TAG="$2"
shift 2
;;
-h|--help)
echo "Usage: $0 [OPTIONS]"
echo ""
echo "Options:"
echo " --no-cache Do not use cache when building"
echo " --quiet Suppress build output except final result"
echo " --skip-tests Skip running tests after build"
echo " --platforms Specify platforms to build for (default: $PLATFORMS)"
echo " -t, --tag Set image tag (default: $TAG)"
echo " -h, --help Show this help message"
echo ""
echo "Examples:"
echo " $0 # Build with default settings"
echo " $0 --no-cache # Build without using cache"
echo " $0 --tag v1.0.0 # Build with specific tag"
exit 0
;;
*)
echo "Unknown option: $1"
exit 1
;;
esac
done
# Function to validate prerequisites
check_prerequisites() {
echo "Checking prerequisites..."
# Check if Docker is available
if ! command -v docker &> /dev/null; then
echo "Error: Docker is not installed or not in PATH"
exit 1
fi
# Check if Docker daemon is running
if ! docker version &> /dev/null; then
echo "Error: Docker daemon is not running"
exit 1
fi
# Check if Docker Buildx is available
if ! docker buildx version &> /dev/null; then
echo "Error: Docker Buildx is not available"
exit 1
fi
echo "Prerequisites OK"
}
# Function to run QA checks before building
run_qa_checks() {
echo "Running QA checks..."
# Check if Dockerfile exists
if [ ! -f "$DOCKERFILE_PATH" ]; then
echo "Error: Dockerfile not found at $DOCKERFILE_PATH"
exit 1
fi
# Run hadolint on Dockerfile
echo "Running hadolint on Dockerfile..."
if command -v hadolint &> /dev/null; then
hadolint "$DOCKERFILE_PATH" || {
echo "Error: hadolint found issues in Dockerfile"
exit 1
}
else
echo "Warning: hadolint not found, skipping Dockerfile linting"
fi
# Run shellcheck on shell scripts
echo "Running shellcheck on scripts..."
for script in run.sh build.sh test.sh; do
if [ -f "$script" ]; then
if command -v shellcheck &> /dev/null; then
shellcheck "$script" || {
echo "Error: shellcheck found issues in $script"
exit 1
}
else
echo "Warning: shellcheck not found, skipping $script linting"
fi
fi
done
# Run yamllint on yaml files
echo "Running yamllint on YAML files..."
if command -v yamllint &> /dev/null; then
yamllint docker-compose.yml || {
echo "Error: yamllint found issues in docker-compose.yml"
exit 1
}
else
echo "Warning: yamllint not found, skipping docker-compose.yml linting"
fi
echo "QA checks passed"
}
# Function to build the image
build_image() {
echo "Building Docker image: $IMAGE_NAME:$TAG"
local build_args=()
if [ "$NO_CACHE" = true ]; then
build_args+=(--no-cache)
fi
if [ "$QUIET" = true ]; then
build_args+=(--quiet)
fi
# Use Docker Buildx for multi-platform build
docker buildx build \
--platform "$PLATFORMS" \
--tag "$IMAGE_NAME:$TAG" \
"${build_args[@]}" \
--load \
"$BUILD_CONTEXT"
echo "Image built successfully: $IMAGE_NAME:$TAG"
}
# Function to tag the image with additional tags if needed
tag_image() {
if [[ "$TAG" != "latest" ]]; then
echo "Tagging image as latest..."
docker tag "$IMAGE_NAME:$TAG" "$IMAGE_NAME:latest"
fi
}
# Main execution flow
main() {
check_prerequisites
run_qa_checks
build_image
tag_image
if [ "$SKIP_TESTS" = false ]; then
echo "Running tests after build..."
if [ -f "./test.sh" ]; then
./test.sh
else
echo "Warning: test.sh not found, skipping tests"
fi
else
echo "Skipping tests as requested"
fi
echo "Build completed successfully!"
}
main "$@"