velxio/Dockerfile.standalone

# ---- Stage 0: QEMU .so + ROM binaries ----
# Downloads arch-specific .so from GitHub Release (e.g. libqemu-xtensa-amd64.so)
# and renames to libqemu-xtensa.so so the backend needs no changes.
# Local prebuilt files (prebuilt/qemu/) are used if present.
FROM ubuntu:22.04 AS qemu-provider

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

ARG TARGETARCH
ARG QEMU_RELEASE_URL=https://github.com/davidmonterocrespo24/velxio/releases/download/qemu-prebuilt

# Copy the prebuilt directory (may contain .so+ROM files or just the .gitkeep)
RUN mkdir -p /qemu
COPY prebuilt/qemu/ /qemu/

# Download arch-specific .so and arch-independent ROM files
RUN cd /qemu \
 && for base in libqemu-xtensa libqemu-riscv32; do \
      f="${base}.so" ; \
      if [ ! -f "$f" ]; then \
        echo "Downloading ${base}-${TARGETARCH}.so → $f ..." ; \
        curl -fSL -o "$f" "${QEMU_RELEASE_URL}/${base}-${TARGETARCH}.so" ; \
      else \
        echo "Using local $f ($(stat -c%s "$f") bytes)" ; \
      fi ; \
    done \
 && for f in esp32-v3-rom.bin esp32-v3-rom-app.bin esp32c3-rom.bin; do \
      if [ ! -f "$f" ]; then \
        echo "Downloading $f ..." ; \
        curl -fSL -o "$f" "${QEMU_RELEASE_URL}/$f" ; \
      else \
        echo "Using local $f ($(stat -c%s "$f") bytes)" ; \
      fi ; \
    done \
 && ls -lh /qemu/


# ---- Stage 0.5: ESP-IDF toolchain for ESP32 compilation ----
FROM ubuntu:22.04 AS espidf-builder

RUN apt-get update && apt-get install -y --no-install-recommends \
    git wget flex bison gperf python3 python3-pip python3-venv \
    cmake ninja-build ccache libffi-dev libssl-dev \
    libusb-1.0-0 ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Install ESP-IDF 4.4.7 (matches Arduino ESP32 core 2.0.17 / lcgamboa QEMU ROM)
RUN git clone -b v4.4.7 --recursive --depth=1 --shallow-submodules \
    https://github.com/espressif/esp-idf.git /opt/esp-idf

WORKDIR /opt/esp-idf

# Install toolchains for esp32 (Xtensa) and esp32c3 (RISC-V) only
RUN ./install.sh esp32,esp32c3

# Clean up large unnecessary files to reduce image size
RUN rm -rf .git docs examples \
    && find /root/.espressif -name '*.tar.*' -delete 2>/dev/null || true

# Install Arduino-as-component for full Arduino API support in ESP-IDF builds
RUN git clone --branch 2.0.17 --depth=1 --recursive --shallow-submodules \
    https://github.com/espressif/arduino-esp32.git /opt/arduino-esp32 \
 && rm -rf /opt/arduino-esp32/.git


# ---- Stage 1: Build frontend and third-party ----
FROM node:20 AS frontend-builder

WORKDIR /app

# avr8js, rp2040js and @wokwi/elements are pulled directly from the npm
# registry (see frontend/package.json) — no upstream git clones needed.
# Board SVGs live in frontend/public/boards/, component SVGs in
# frontend/public/component-svgs/, and components-metadata.json is committed.
COPY frontend/ frontend/
COPY scripts/ scripts/
WORKDIR /app/frontend
# Lock files aren't committed in this repo (they're gitignored) — see the
# note in .gitignore. The `rm -f` below is defense-in-depth in case
# someone runs `docker build .` from a tree where a local lock exists.
RUN rm -f package-lock.json \
 && npm install --include=optional \
 && npm run build:docker


# ---- Stage 2: Final Production Image ----
FROM python:3.12-slim

# Install system dependencies, nginx, and QEMU .so runtime libraries
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    nginx \
    libglib2.0-0 \
    libgcrypt20 \
    libslirp0 \
    libpixman-1-0 \
    libfdt1 \
    cmake \
    ninja-build \
    libusb-1.0-0 \
    git \
    ccache \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/* \
    && pip install --no-cache-dir packaging

# Install arduino-cli into /usr/local/bin directly (avoids touching /bin)
RUN curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh \
    | BINDIR=/usr/local/bin sh

# Only install arduino-cli binary here. Core installation (arduino:avr,
# rp2040:rp2040) is done at first boot by entrypoint.sh and persisted
# in the mounted /root/.arduino15 volume.
# ESP32 compilation uses ESP-IDF instead of arduino-cli.

WORKDIR /app

# Data directory for persistent SQLite database (mounted as a volume at runtime)
RUN mkdir -p /app/data

# Install Python backend dependencies
COPY backend/requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy backend application code
COPY backend/app/ ./app/

# One-off maintenance scripts (e.g. backfill_boards_2026_05). Pure stdlib —
# run with: docker exec velxio-app python /app/scripts/<script> --apply
COPY backend/scripts/ ./scripts/

# Setup Nginx configuration. Remove Debian's stock site so it doesn't shadow
# ours as the default_server (was Issue #108: users behind reverse proxies got
# the "Welcome to nginx" page because the stock site claimed default_server).
RUN rm -f /etc/nginx/sites-enabled/default
COPY docker/nginx.conf /etc/nginx/conf.d/default.conf

# Copy built frontend assets from builder stage
COPY --from=frontend-builder /app/frontend/dist /usr/share/nginx/html

# Copy and configure entrypoint script (fix Windows CRLF → LF)
COPY docker/entrypoint.sh /app/entrypoint.sh
RUN sed -i 's/\r$//' /app/entrypoint.sh && chmod +x /app/entrypoint.sh

# ── ESP32 emulation: pre-built QEMU .so + ROM binaries ──────────────────────
# Downloaded from GitHub Release (public — no access to qemu-lcgamboa needed)
# libqemu-xtensa.so    → ESP32 / ESP32-S3 (Xtensa LX6/LX7)
# libqemu-riscv32.so   → ESP32-C3 (RISC-V RV32IMC)
# esp32-v3-rom*.bin    → boot/app ROM images required by esp32-picsimlab machine
# esp32c3-rom.bin      → ROM image required by esp32c3-picsimlab machine
# NOTE: ROM files must live in the same directory as the .so (worker passes -L
#       to QEMU pointing at os.path.dirname(lib_path))
RUN mkdir -p /app/lib
COPY --from=qemu-provider /qemu/ /app/lib/

# Activate ESP32 emulation
# QEMU_ESP32_LIB    → Xtensa library (ESP32, ESP32-S3)
# QEMU_RISCV32_LIB  → RISC-V library (ESP32-C3 and variants)
ENV QEMU_ESP32_LIB=/app/lib/libqemu-xtensa.so
ENV QEMU_RISCV32_LIB=/app/lib/libqemu-riscv32.so

# ── ESP-IDF toolchain for ESP32 compilation ──────────────────────────────────
# Copied from espidf-builder stage: IDF framework + cross-compiler toolchains
COPY --from=espidf-builder /opt/esp-idf /opt/esp-idf
COPY --from=espidf-builder /root/.espressif /root/.espressif

COPY --from=espidf-builder /opt/arduino-esp32 /opt/arduino-esp32

ENV IDF_PATH=/opt/esp-idf
ENV IDF_TOOLS_PATH=/root/.espressif
ENV ARDUINO_ESP32_PATH=/opt/arduino-esp32

# ── ccache for ESP-IDF compiles ──────────────────────────────────────────────
# ESP-IDF's build system honours IDF_CCACHE_ENABLE=1 and routes every C/C++
# compile through ccache. Cold first compile per container is unchanged
# (cache is empty), but the second and subsequent compiles drop from
# ~5-7 minutes to ~30-60 seconds because every ESP-IDF base object
# (FreeRTOS, lwIP, esp_wifi, libsodium, …) hits the cache.
#
# Cache lives at /var/cache/ccache. Mount as a docker volume in
# docker-compose.yml so the cache survives `docker compose up -d --build`.
# Without the volume, the cache rebuilds itself on first compile after each
# image rebuild — still better than no cache.
ENV CCACHE_DIR=/var/cache/ccache
ENV IDF_CCACHE_ENABLE=1
# CCACHE_BASEDIR makes ccache treat absolute paths under this prefix as
# relative when computing the cache key. Combined with the persistent
# /var/lib/velxio-build/<target>/ build dir, this lets ccache hit across
# compiles even though some flags (-I, -fmacro-prefix-map) embed absolute
# paths into the command line.
ENV CCACHE_BASEDIR=/var/lib/velxio-build
# Cache cap + compression set as env vars (rather than via `ccache
# --set-config` at image-build time) because $CCACHE_DIR is a docker volume:
# anything written into /var/cache/ccache during the RUN step is masked at
# runtime by the volume mount. ccache reads CCACHE_MAXSIZE / CCACHE_COMPRESS
# / CCACHE_COMPRESSLEVEL on every invocation and they override any conf-file
# value, so the cap actually applies at runtime.
ENV CCACHE_MAXSIZE=8G
ENV CCACHE_COMPRESS=1
ENV CCACHE_COMPRESSLEVEL=6
RUN mkdir -p /var/cache/ccache /var/lib/velxio-build /root/Arduino

# ── Persistent paths ────────────────────────────────────────────────────────
# Declaring these as VOLUMEs means `docker run` (without explicit -v) creates
# anonymous volumes for them — they survive `docker stop`/`docker start` and
# even `docker rm`. Without this, every container restart wipes the ccache
# and persistent ESP-IDF build dir, so every compile is cold (~5-7 min on
# modest hardware) instead of the warm-cache 5-30s we measured on prod.
#
# Users SHOULD pass `-v velxio-X:/path` for each of these to get named
# volumes (easier to inspect / back up than anonymous ones), but the
# anonymous default is a sensible fallback.
#
# /app/data            — SQLite DB + project files + auto-generated SECRET_KEY
# /root/.arduino15     — arduino-cli config + installed cores
# /root/Arduino        — Library Manager-installed Arduino libraries
# /var/cache/ccache    — ccache cache (ESP-IDF compiles)
# /var/lib/velxio-build — persistent ESP-IDF build dir (one subdir per target)
VOLUME ["/app/data", "/root/.arduino15", "/root/Arduino", "/var/cache/ccache", "/var/lib/velxio-build"]

# Install ESP-IDF Python dependencies using the final image's Python
# The requirements.txt has version constraints required by ESP-IDF 4.4.x
RUN grep -v 'esp-windows-curses' /opt/esp-idf/requirements.txt \
    | pip install --no-cache-dir -r /dev/stdin

EXPOSE 80

CMD ["/app/entrypoint.sh"]