gh-christianlouis-docuelevate/docs/BuildMetadata.md

Build Metadata Automation

Overview

DocuElevate automatically generates and embeds build metadata (version, build date, Git commit SHA) into the application at build time. This metadata is displayed in the /status endpoint and helps track which version of the application is running in production.

What is Automated

The following metadata is automatically generated and included in every build:

1. Build Date - The UTC date when the build was created (format: YYYY-MM-DD)
2. Git Commit SHA - The short Git commit hash (7 characters) of the code being built
3. Runtime Information - A comprehensive summary including version, dates, commit info, and more
4. Application Version - Read from the VERSION file (manually updated for releases)

How It Works

Build Time Generation

When the Docker image is built (locally or in CI/CD), the following happens:

1. GitHub Actions runs the metadata script (scripts/generate_build_metadata.sh) before building the Docker image
2. The script generates three files:
   • BUILD_DATE - Contains the build date in YYYY-MM-DD format
   • GIT_SHA - Contains the short Git commit hash
   • RUNTIME_INFO - Contains detailed build information
3. Docker copies these files into the image during the build process
4. The application reads the files at runtime via app/config.py properties

File Structure

DocuElevate/
├── scripts/
│   └── generate_build_metadata.sh    # Script that generates metadata
├── VERSION                             # Manually maintained version number
├── BUILD_DATE                          # Generated at build time (gitignored)
├── GIT_SHA                            # Generated at build time (gitignored)
└── RUNTIME_INFO                        # Generated at build time (gitignored)

Generated Files Format

BUILD_DATE:

2026-02-07

GIT_SHA:

6812d0d

RUNTIME_INFO:

DocuElevate Build Information
==============================
Version: 0.4.5-dev
Build Date: 2026-02-07
Git Commit: 6812d0d2c42a4782e78840b052f0e6da24ec8543
Git Short SHA: 6812d0d
Git Branch: main
Commit Date: 2026-02-07T19:32:04Z
Build Timestamp: 2026-02-07T19:34:10Z
==============================

Configuration Properties

The app/config.py Settings class provides these properties for accessing build metadata:

settings.version (property)

Returns the application version with the following priority:

1. APP_VERSION environment variable
2. Contents of VERSION file
3. Default: "0.3.2-dev"

settings.build_date (property)

Returns the build date with the following priority:

1. BUILD_DATE environment variable
2. Contents of BUILD_DATE file
3. Default: "Unknown build date"

settings.git_sha (property)

Returns the Git commit SHA with the following priority:

1. GIT_COMMIT_SHA environment variable
2. Contents of GIT_SHA file
3. Default: "unknown"

settings.runtime_info (property)

Returns detailed runtime information:

1. Contents of RUNTIME_INFO file
2. Default: Basic info string with version, build date, and Git SHA

Usage in Application

In Python Code

from app.config import settings

# Get version
version = settings.version  # "0.4.5-dev"

# Get build date
build_date = settings.build_date  # "2026-02-07"

# Get Git SHA
git_sha = settings.git_sha  # "6812d0d"

# Get full runtime info
runtime_info = settings.runtime_info  # Full multi-line string

In Templates

The /status endpoint uses these properties to display metadata:

# app/views/status.py
return templates.TemplateResponse(
    "status_dashboard.html",
    {
        "app_version": settings.version,
        "build_date": settings.build_date,
        "container_info": {
            "git_sha": settings.git_sha[:7],
            "runtime_info": settings.runtime_info,
        }
    }
)

GitHub Actions Integration

The build metadata is generated in two GitHub Actions workflows:

docker-build.yaml

- name: Generate Build Metadata
  run: |
    chmod +x scripts/generate_build_metadata.sh
    ./scripts/generate_build_metadata.sh

docker-ci.yml

- name: Generate Build Metadata
  run: |
    chmod +x scripts/generate_build_metadata.sh
    ./scripts/generate_build_metadata.sh

These steps run before the Docker build step, ensuring the metadata files exist when Docker copies them into the image.

Local Development

Manual Generation

To generate build metadata locally:

# Run the script
./scripts/generate_build_metadata.sh

# Output:
# Generating build metadata...
# ✓ BUILD_DATE: 2026-02-07
# ✓ GIT_SHA: 6812d0d
# ✓ VERSION: 0.4.5-dev
# ✓ RUNTIME_INFO generated

Local Docker Build

When building Docker images locally:

# Generate metadata first
./scripts/generate_build_metadata.sh

# Then build the Docker image
docker build -t docuelevate:local .

# Or use docker-compose
docker-compose build

Testing Without Docker

The application will still work without the generated files:

• BUILD_DATE will show "Unknown build date"
• GIT_SHA will show "unknown"
• The app will use defaults from app/config.py

Environment Variable Override

You can override any metadata value using environment variables:

# Override version
export APP_VERSION="1.0.0-custom"

# Override build date
export BUILD_DATE="2026-01-15"

# Override Git SHA
export GIT_COMMIT_SHA="abc1234"

# Run the application
python -m uvicorn app.main:app

This is useful for:

• Custom builds
• Testing different versions
• Development environments

Updating the Version

The VERSION file must be manually updated for releases:

# Update version for a new release
echo "0.5.0" > VERSION

# Commit the change
git add VERSION
git commit -m "Bump version to 0.5.0"
git tag v0.5.0
git push origin main --tags

The build metadata script will automatically include this version in all builds.

Troubleshooting

Problem: Build metadata shows "unknown"

Solution: Ensure the script runs before Docker build:

./scripts/generate_build_metadata.sh
docker build -t docuelevate .

Problem: Git SHA is "unknown"

Cause: Building outside of a Git repository

Solution:

• Clone the repository properly with .git directory
• Or set GIT_COMMIT_SHA environment variable

Problem: Build date is outdated

Cause: Using cached Docker layers

Solution:

# Rebuild without cache
docker build --no-cache -t docuelevate .

Problem: Files not copied to Docker image

Cause: Files listed in .dockerignore

Solution:

• Check .dockerignore doesn't block BUILD_DATE, GIT_SHA, or RUNTIME_INFO
• The VERSION file should always be committed to git

Best Practices

1. Always run the script before building - The CI/CD pipeline does this automatically
2. Don't commit generated files - GIT_SHA and RUNTIME_INFO are in .gitignore
3. Update VERSION manually - Only update for actual releases
4. Use semantic versioning - Follow MAJOR.MINOR.PATCH format
5. Tag releases in Git - Create Git tags for version releases

CI/CD Pipeline Flow

┌─────────────────────────────────────────────────────────────┐
│ GitHub Actions Workflow                                     │
├─────────────────────────────────────────────────────────────┤
│ 1. Checkout Code                                            │
│ 2. Generate Build Metadata (run script)                     │
│    - Creates BUILD_DATE                                     │
│    - Creates GIT_SHA                                        │
│    - Creates RUNTIME_INFO                                   │
│ 3. Build Docker Image                                       │
│    - Copies VERSION (from git)                              │
│    - Copies BUILD_DATE (generated)                          │
│    - Copies GIT_SHA (generated)                             │
│    - Copies RUNTIME_INFO (generated)                        │
│ 4. Push to Docker Hub / GHCR                                │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ Running Container                                           │
├─────────────────────────────────────────────────────────────┤
│ Application reads metadata from files in /app:              │
│ - /app/VERSION                                              │
│ - /app/BUILD_DATE                                           │
│ - /app/GIT_SHA                                              │
│ - /app/RUNTIME_INFO                                         │
│                                                              │
│ Displays in /status endpoint                                │
└─────────────────────────────────────────────────────────────┘

Future Enhancements

Potential improvements to the build metadata system:

1. Automated version bumping - Automatically increment version based on commits
2. Changelog generation - Auto-generate changelog from Git history
3. Build number tracking - Track sequential build numbers
4. Deployment tracking - Record when/where each build was deployed
5. Performance metrics - Include build time, image size, etc.

Related Documentation

• Deployment Guide - How to deploy DocuElevate
• Configuration Guide - All configuration options
• API Documentation - API endpoints including /status