Trackeep/docs/VERSION_WORKFLOW.md

Trackeep Version Management & Update Workflow

📍 Where Version Comes From

Current Version Detection:

1. Backend: APP_VERSION environment variable (defaults to "1.0.0")
2. Frontend: VITE_APP_VERSION environment variable (passed during build)

Version Priority Order:

1. __APP_VERSION__ build constant (highest priority)
2. VITE_APP_VERSION environment variable (frontend)
3. APP_VERSION environment variable (backend)
4. Falls back to "1.0.0" (default)

---

🏷️ How to Set Version Properly

Option 1: Environment Variables (Recommended)

Development:

# Set version in .env file
echo "APP_VERSION=1.2.0" >> .env

# Start with version
docker compose up

Production:

# Set version environment variable
export APP_VERSION=1.2.0
docker compose -f docker-compose.prod.yml up

Option 2: Build-time Constants

Frontend (vite.config.ts):

export default defineConfig({
  define: {
    __APP_VERSION__: JSON.stringify(process.env.npm_package_version || '1.0.0')
  },
  // ... rest of config
})

Backend (build):

# Build with version
APP_VERSION=1.2.0 go build -ldflags "-X main.version=${APP_VERSION}"

---

🚀 How to Push Updates with Proper Labels

Method 1: GitHub Actions (Recommended)

Create .github/workflows/release.yml:

name: Release and Deploy

on:
  push:
    tags:
      - 'v*'  # Trigger on version tags like v1.2.0

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
        
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
          
      - name: Extract version from tag
        run: |
          VERSION=${GITHUB_REF#refs/tags/v*}
          VERSION=${VERSION#refs/tags/v}
          echo "VERSION=$VERSION" >> $GITHUB_ENV
          echo "Building version: $VERSION"
          
      - name: Build and push backend
        uses: docker/build-push-action@v5
        with:
          context: ./backend
          file: ./backend/Dockerfile
          push: true
          tags: |
            ghcr.io/dvorinka/trackeep/backend:latest
            ghcr.io/dvorinka/trackeep/backend:${{ env.VERSION }}
          labels: |
            version=${{ env.VERSION }}
            build-date=${{ github.event.head_commit.timestamp }}
            commit=${{ github.sha }}
            
      - name: Build and push frontend
        uses: docker/build-push-action@v5
        with:
          context: .
          file: ./frontend/Dockerfile
          push: true
          tags: |
            ghcr.io/dvorinka/trackeep/frontend:latest
            ghcr.io/dvorinka/trackeep/frontend:${{ env.VERSION }}
          labels: |
            version=${{ env.VERSION }}
            build-date=${{ github.event.head_commit.timestamp }}
            commit=${{ github.sha }}

Method 2: Manual Docker Push

Tag and Push:

# Set version
export VERSION=1.2.0

# Build and tag with version
docker build -t ghcr.io/dvorinka/trackeep/backend:${VERSION} ./backend
docker build -t ghcr.io/dvorinka/trackeep/backend:latest ./backend

docker build -t ghcr.io/dvorinka/trackeep/frontend:${VERSION} .
docker build -t ghcr.io/dvorinka/trackeep/frontend:latest .

# Push both tags
docker push ghcr.io/dvorinka/trackeep/backend:${VERSION}
docker push ghcr.io/dvorinka/trackeep/backend:latest

docker push ghcr.io/dvorinka/trackeep/frontend:${VERSION}
docker push ghcr.io/dvorinka/trackeep/frontend:latest

# Create Git tag
git tag v${VERSION}
git push origin v${VERSION}

---

📋 How People Do It (Industry Standards)

Semantic Versioning:

MAJOR.MINOR.PATCH
1.2.0
│ │ └─ PATCH: Bug fixes, small features
│ └─ MINOR: New features, breaking changes
└─ MAJOR: Major changes, breaking API

Version Labels:

# In Dockerfile
LABEL version="1.2.0"
LABEL build-date="2024-02-27"
LABEL commit="abc123def"

Environment Variables:

# Production
APP_VERSION=1.2.0
VITE_APP_VERSION=1.2.0

# Development
APP_VERSION=1.3.0-dev
VITE_APP_VERSION=1.3.0-dev

Git Tags:

# Create version tag
git tag -a v1.2.0 -m "Release version 1.2.0"
git push origin v1.2.0

# Lightweight tags (for CI/CD)
git tag v1.2.0 ${COMMIT_SHA}
git push origin v1.2.0

---

🔄 Update Detection Logic

How System Detects Updates:

Current Setup:

// Backend gets current version
currentVersion := os.Getenv("APP_VERSION")
if currentVersion == "" {
    currentVersion = "1.0.0"
}

// Frontend gets version from build
return import.meta.env.VITE_APP_VERSION || '1.0.0'

Update Check:

// Compares current vs latest
if isNewerVersion("latest", currentVersion) {
    // Update available!
    return updateInfo, true, nil
}

---

🎯 Recommended Workflow

Development:

# 1. Set version in .env
echo "APP_VERSION=1.2.1-dev" >> .env

# 2. Start development
docker compose up

# 3. Test updates
curl http://localhost:8080/api/updates/check

Production Release:

# 1. Update version
export APP_VERSION=1.2.1

# 2. Build and push
./scripts/release.sh 1.2.1

# 3. Deploy
docker compose -f docker-compose.prod.yml up -d

Version Update Process:

1. Code changes → Commit to main branch
2. Version bump → Update APP_VERSION in .env
3. Tag release → git tag v1.2.1 && git push origin v1.2.1
4. Auto-build → GitHub Actions builds Docker images
5. Push tags → latest + versioned tags to registry
6. Deploy → Users get updates automatically

---

✅ Best Practices

Version Management:

• ✅ Use semantic versioning (MAJOR.MINOR.PATCH)
• ✅ Always update both frontend and backend versions
• ✅ Use environment variables for flexibility
• ✅ Tag releases in Git

Docker Tags:

• ✅ Always push latest tag for updates
• ✅ Also push versioned tags for rollback
• ✅ Add labels for metadata
• ✅ Use consistent naming convention

Release Process:

• ✅ Automate with GitHub Actions
• ✅ Test before tagging
• ✅ Document changes in release notes
• ✅ Use semantic versioning

---

🧪 Testing Your Setup

Test Version Detection:

# Check current version
curl -s http://localhost:8080/api/updates/check | jq '.currentVersion'

# Should return your APP_VERSION value

Test Update Detection:

# Simulate update available
# Backend will show "latest" vs your current version

Verify Docker Images:

# Check if images have version labels
docker inspect ghcr.io/dvorinka/trackeep/backend:latest | jq '.[0].Config.Labels.version'
docker inspect ghcr.io/dvorinka/trackeep/frontend:latest | jq '.[0].Config.Labels.version'

This system ensures proper versioning and update detection for your Trackeep application!