docs: update documentation with CI image info

.gitea/workflows/ci-image-builder.yml

@@ -0,0 +1,82 @@
+# CI Image Builder Workflow
+# Automatically builds and pushes CI images when dependencies change
+# Uses GitHub Container Registry (GHCR) or any container registry
+
+name: CI Image Builder
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'package.json'
+      - 'package-lock.json'
+      - 'Dockerfile.ci'
+      - '.gitea/workflows/ci-image-builder.yml'
+  workflow_dispatch:
+    inputs:
+      force_rebuild:
+        description: 'Force rebuild even if no changes detected'
+        required: false
+        default: 'false'
+        type: boolean
+
+env:
+  # Use GHCR or your own registry
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/ci-runner
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=sha,prefix={{branch}}-
+            type=ref,event=branch
+            type=ref,event=pr
+            type=raw,value=latest,enable={{is_default_branch}}
+
+      - name: Build and push CI image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: Dockerfile.ci
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      - name: Update workflow documentation
+        run: |
+          echo "CI Image built and pushed successfully!"
+          echo ""
+          echo "Available tags:"
+          echo "  - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest"
+          echo "  - ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}"
+          echo ""
+          echo "To use in workflows:"
+          echo "  container:"
+          echo "    image: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest"

AGENTS.md

@@ -127,6 +127,26 @@ npm run db:setup-postgres
 DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
 ```
 
+### CI Runner Image
+
+To speed up CI runs, the project uses a pre-built CI runner image with all dependencies pre-installed.
+
+**Building the CI image locally:**
+```bash
+./scripts/build-ci-image.sh [tag]
+```
+
+**Using the CI image:**
+- Workflows automatically use `ghcr.io/<repo>/ci-runner:latest` when available
+- Falls back to `node:20-alpine` if image is not found
+- Image is automatically rebuilt when `package.json` changes
+
+**CI Image contains:**
+- Node.js 20 Alpine
+- All npm dependencies pre-installed
+- Prisma client pre-generated
+- System tools (bash, git, python, make, g++)
+
 ### CI/CD Pipeline
 The project uses Gitea Actions for continuous integration:
 

Dockerfile.ci

@@ -0,0 +1,46 @@
+# CI Runner Image for EuchreCamp
+# Pre-installed with all dependencies to speed up CI runs
+# This image is rebuilt automatically when package.json changes
+
+FROM node:20-alpine
+
+# Install system dependencies needed for various tasks
+RUN apk add --no-cache \
+    bash \
+    git \
+    curl \
+    python3 \
+    make \
+    g++ \
+    && rm -rf /var/cache/apk/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy package files first (for better caching)
+COPY package*.json ./
+
+# Install ALL dependencies including dev dependencies
+# This is done at image build time, not at CI runtime
+RUN npm ci
+
+# Copy Prisma schema (needed for Prisma client generation)
+COPY prisma/schema.prisma ./prisma/
+
+# Generate Prisma client
+RUN npx prisma generate
+
+# Copy the rest of the application
+COPY . .
+
+# Set environment variables for CI environment
+ENV NODE_ENV=production
+ENV DATABASE_PROVIDER=sqlite
+ENV DATABASE_URL=file:./prisma/ci.db
+ENV BETTER_AUTH_SECRET=test-secret-key-for-ci-only
+
+# Verify installations
+RUN node --version && npm --version && git --version && npx prisma --version
+
+# Default command
+CMD ["/bin/sh"]

README.md

@@ -373,6 +373,31 @@ The application uses Gitea Actions for continuous integration and deployment:
    - Docker image building and testing
    - Registry push and deployment
 
+4. **CI Image Builder** (`.gitea/workflows/ci-image-builder.yml`): Runs when dependencies change
+   - Automatically builds CI runner image with all dependencies pre-installed
+   - Triggered by changes to `package.json`, `package-lock.json`, or `Dockerfile.ci`
+
+### CI Runner Image
+
+To avoid installing dependencies on every workflow run, we use a pre-built CI runner image:
+
+**Dockerfile.ci** - Contains:
+- Node.js 20 Alpine
+- All npm dependencies pre-installed
+- Prisma client pre-generated
+- System tools (bash, git, python, make, g++)
+
+**Automatic Rebuilding:**
+- The CI image is automatically rebuilt when `package.json` or `package-lock.json` changes
+- Images are tagged with commit SHA for traceability
+- Falls back to `node:20-alpine` if custom image is not available
+
+**Manual Build:**
+```bash
+docker build -f Dockerfile.ci -t euchre-camp-ci:latest .
+docker run --rm euchre-camp-ci:latest node --version
+```
+
 ### Database Strategy for CI
 - **CI Tests**: SQLite database (fast, no server required)
 - **Production**: PostgreSQL (production-like environment)
@@ -385,6 +410,9 @@ npm run test:run
 
 # Run acceptance tests with SQLite
 DATABASE_PROVIDER=sqlite DATABASE_URL=file:./prisma/ci.db npm run test:acceptance
+
+# Run tests in CI container (if built)
+docker run --rm -v $(pwd):/app -w /app euchre-camp-ci:latest npm run test:run
 ```
 
 ## Docker Deployment

justfile

@@ -173,6 +173,16 @@ pr-validate: lint typecheck test-unit test-acceptance-sqlite
 ci-postgres: lint typecheck test-unit test-acceptance-postgres docker-build
     @echo "CI Pipeline with PostgreSQL completed successfully!"
 
+# --- CI Image ---
+
+# Build CI runner image locally
+ci-build:
+    @./scripts/build-ci-image.sh
+
+# Build CI runner image with custom tag
+ci-build-tag TAG:
+    @./scripts/build-ci-image.sh {{TAG}}
+
 # --- Utilities ---
 
 # Show help information

scripts/build-ci-image.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Build and test the CI runner image locally
+
+set -e
+
+IMAGE_NAME="euchre-camp-ci"
+TAG="${1:-latest}"
+
+echo "Building CI runner image..."
+echo "Image: ${IMAGE_NAME}:${TAG}"
+echo ""
+
+# Build the image
+docker build \
+    -f Dockerfile.ci \
+    -t ${IMAGE_NAME}:${TAG} \
+    .
+
+echo ""
+echo "✅ Image built successfully!"
+echo ""
+
+# Test the image
+echo "Testing CI image..."
+docker run --rm ${IMAGE_NAME}:${TAG} sh -c "
+    echo 'Node.js version:' && node --version
+    echo 'npm version:' && npm --version
+    echo 'Git version:' && git --version
+    echo 'Prisma version:' && npx prisma --version
+    echo ''
+    echo 'Installed packages (top 10):'
+    npm list --depth=0 | head -10
+"
+
+echo ""
+echo "✅ CI image is ready to use!"
+echo ""
+echo "To use in GitHub Actions/Gitea Actions:"
+echo "  container:"
+echo "    image: ${IMAGE_NAME}:${TAG}"
+echo ""
+echo "To push to registry:"
+echo "  docker tag ${IMAGE_NAME}:${TAG} registry.example.com/${IMAGE_NAME}:${TAG}"
+echo "  docker push registry.example.com/${IMAGE_NAME}:${TAG}"