# ContainerCraft Dockerfile Quick Reference v1.0.0

## Essential Patterns

### File Header
```dockerfile
###############################################################################
# Use:
# - docker build --progress plain --tag ghcr.io/[org]/[image]:[tag] -f docker/[variant]/Dockerfile ./docker
# - docker run --rm -d --name [container] --hostname [hostname] ghcr.io/[org]/[image]:[tag]
###############################################################################
```

### Base Setup
```dockerfile
FROM ghcr.io/containercraft/devcontainer:base
LABEL tag="variant-name"
ENV DEVCONTAINER="variant-name"
```

### Tool Installation Template
```dockerfile
RUN echo \
  && export NAME=toolname \
  && export TEST="${NAME} --version" \
  && export REPOSITORY="owner/repo" \
  && export VERSION="$(${curl} https://api.github.com/repos/${REPOSITORY}/releases/latest | jq --raw-output .tag_name)" \
  && export ARCH=$(uname -m | awk '{ if ($1 == "x86_64") print "amd64"; else if ($1 == "aarch64" || $1 == "arm64") print "arm64"; else print "unknown" }') \
  && export PKG="${NAME}-linux-${ARCH}.tar.gz" \
  && export URL="https://github.com/${REPOSITORY}/releases/download/${VERSION}/${PKG}" \
  && echo "---------------------------------------------------------"\
  && echo "INFO[${NAME}] Installed:" \
  && echo "INFO[${NAME}]   Command:        ${NAME}" \
  && echo "INFO[${NAME}]   Package:        ${PKG}" \
  && echo "INFO[${NAME}]   Latest Release: ${VERSION}" \
  && echo "INFO[${NAME}]   Architecture:   ${ARCH}" \
  && echo "INFO[${NAME}]   Source:         ${URL}" \
  && echo "---------------------------------------------------------"\
  && ${curl} ${URL} --output /tmp/${NAME} \
  && sudo ${INSTALL} /tmp/${NAME} ${BIN}/${NAME} \
  && ${dir_clean} \
  && ${TEST} \
  && echo
```

### APT Package Installation
```dockerfile
ARG APT_PKGS="\
  package1 \
  package2 \
  "
RUN echo \
  && export TEST="command --version" \
  && ${apt_update} \
  && bash -c "${apt_install} --no-install-recommends -o Dpkg::Options::='--force-confold' ${APT_PKGS}" \
  && bash -c "${apt_clean}" \
  && ${dir_clean} \
  && ${TEST} \
  && echo
```

## Formatting Rules

| Element | Length | Character | Usage |
|---------|--------|-----------|-------|
| Header/Footer | 79 | `#` | File boundaries |
| Section Header | 80+ | `#` | Major sections |
| Info Separator | 57 | `-` | Tool info blocks |

## Environment Variables (Defined in Slim)

```dockerfile
ENV apt_update="sudo apt-get update"
ENV apt_install="TERM=linux DEBIAN_FRONTEND=noninteractive sudo apt-get install -q --yes --purge --assume-yes --auto-remove --allow-downgrades -o Dpkg::Options::='--force-confdef' -o Dpkg::Options::='--force-confold'"
ENV apt_clean="sudo apt-get clean && sudo apt-get autoremove -y && sudo apt-get purge -y --auto-remove"
ENV curl="/usr/bin/curl --silent --show-error --tlsv1.2 --location"
ENV curl_github="/usr/bin/curl --silent --show-error --tlsv1.2 --request GET --url"
ENV BIN="/usr/local/bin"
ENV INSTALL="install -m 755 -o root -g root"
ENV dir_clean="sudo rm -rf /var/lib/{apt,cache,log} /usr/share/{doc,man,locale} /var/cache/apt /home/*/.cache /root/.cache /var/tmp/* /tmp/*"
```

## Architecture Detection

```bash
# Standard mapping
$(uname -m | awk '{ if ($1 == "x86_64") print "amd64"; else if ($1 == "aarch64" || $1 == "arm64") print "arm64"; else print "unknown" }')

# Alternative for some tools
$(uname -m | awk '{ if ($1 == "x86_64") print "x64"; else if ($1 == "aarch64" || $1 == "arm64") print "arm64"; else print "unknown" }')

# Direct architecture (ttyd)
$(uname -m | awk '{ if ($1 == "x86_64") print "x86_64"; else if ($1 == "aarch64" || $1 == "arm64") print "aarch64"; else print "unknown" }')
```

## User Creation

```dockerfile
# Primary user (UID 1000)
export USER_ID="1000"
export USER_NAME="ubuntu"

# Secondary users (UID 1001+)
export USER_ID="1001"
export USER_NAME="runner"
```

## Common Test Commands

- `${NAME} --version` (preferred)
- `${NAME} version` (alternative)
- `command -v ${NAME}` (existence check)
- `fc-list --quiet ${NAME}` (fonts)

## Cleanup Requirements

Always include in RUN commands:
1. `${dir_clean}` - Remove caches and temp files
2. `${apt_clean}` - Clean APT after installations
3. `|| true` - For operations that might safely fail

## Section Comment Examples

```dockerfile
#################################################################################
# Base package and user configuration
#################################################################################

##################################################################################
# Install Programming Language Tooling
# - python
#################################################################################

##################################################################################
# Install Tool Name
# - https://tool.website
# - https://github.com/owner/repo
```

## Final Image Structure

```dockerfile
# Load startup artifacts (if needed)
COPY ./bin/entrypoint /bin/

# Entrypoint & default command
ENTRYPOINT ["/usr/bin/bash", "-c", "entrypoint"]
HEALTHCHECK --interval=120s --timeout=30s --start-period=5s --retries=3 CMD [ "true" ]

#################################################################################
# Image Metadata
LABEL name="ContainerCraft Konductor Devcontainer"
LABEL io.k8s.display-name="ContainerCraft Konductor Devcontainer"
LABEL org.opencontainers.image.authors="github.com/ContainerCraft"
LABEL org.opencontainers.image.source="https://github.com/containercraft/devcontainer"
LABEL org.opencontainers.image.licenses="APACHE-2.0"
LABEL distribution-scope="public"
```