Sasha Studio Docker Versioning Guide

Overview

This document describes the semantic versioning system implemented for Sasha Studio Docker builds. The system provides both local and CI/CD-based versioning approaches, ensuring consistent version management across development, testing, and production environments.

Version Format

We follow Semantic Versioning 2.0.0 with the format:

MAJOR.MINOR.PATCH[-PRERELEASE][+BUILD]

Version Components

MAJOR: Breaking changes that are incompatible with previous versions
MINOR: New features added in a backward-compatible manner
PATCH: Backward-compatible bug fixes
PRERELEASE: Optional pre-release identifier (alpha, beta, rc)
BUILD: Optional build metadata (date, commit hash)

Examples

1.0.0 - First stable release
1.1.0 - Added new feature
1.0.1 - Bug fix
2.0.0-beta.1 - Beta version of major release
1.0.0+20240111.abc123 - Build with metadata

Version Management

Central Version File

The version is maintained in a single VERSION file at the project root:

/sasha/VERSION

This file contains only the version number (e.g., 1.0.0) and serves as the single source of truth for all versioning operations.

Automatic Version Bumping

NEW: The build.sh script now automatically bumps the patch version on each build:

./build.sh              # Auto-bumps: 1.0.0 → 1.0.1 → builds
./build.sh --no-bump    # Builds without version change

This ensures every build has a unique version number for better tracking.

Version Script

Use the scripts/version.sh script to manage versions:

# View current version
./scripts/version.sh current

# Bump versions
./scripts/version.sh major    # 1.0.0 -> 2.0.0
./scripts/version.sh minor    # 1.0.0 -> 1.1.0
./scripts/version.sh patch    # 1.0.0 -> 1.0.1

# Create pre-release versions
./scripts/version.sh prerelease beta    # 1.0.0 -> 1.0.0-beta.1
./scripts/version.sh prerelease rc      # 1.0.0 -> 1.0.0-rc.1

# Add build metadata
./scripts/version.sh build    # 1.0.0 -> 1.0.0+20240111.abc123

# Set specific version
./scripts/version.sh set 2.0.0-alpha.1

Docker Build Process

Local Builds

The enhanced claudecodeui/scripts/docker-build.sh script provides comprehensive versioning support and now uses Dockerfile.sliplane by default (optimized for Sliplane deployment):

# Production build with automatic versioning
./claudecodeui/scripts/docker-build.sh production

# Development build
./claudecodeui/scripts/docker-build.sh development

# Custom tagged build
./claudecodeui/scripts/docker-build.sh production my-custom-tag

Docker Tags Created

For a production build of version 1.2.3, the following tags are created:

sasha-studio:1.2.3 - Full version tag
sasha-studio:1.2 - Major.minor tag
sasha-studio:1 - Major version tag
sasha-studio:latest - Latest stable
sasha-studio:production - Production tag

Additional tags for development:

sasha-studio:dev - Development build
sasha-studio:dev-abc123 - Dev with commit hash
sasha-studio:feature-branch - Branch-based tag
sasha-studio:1.2.3-dev.20240111.abc123 - Dev with full metadata

Build Metadata

Each Docker image includes metadata labels:

org.opencontainers.image.version - Version number
org.opencontainers.image.created - Build timestamp
org.opencontainers.image.revision - Git commit hash
org.opencontainers.image.title - Application name
org.opencontainers.image.description - Application description

Testing with Versions

The docker-test.sh script automatically uses the current version:

# Run test environment with current version
./docker-test.sh

# The test container will display:
# 📌 Version: 1.0.0

CI/CD Integration

GitHub Actions

The repository includes GitHub Actions workflows for automated builds:

On Push to Main: Builds and tags as latest
On Git Tag: Builds with semantic version tags
On Pull Request: Builds with PR number tag

Creating a Release

# 1. Update version
./scripts/version.sh minor

# 2. Commit changes
git add -A
git commit -m "chore: bump version to 1.1.0"

# 3. Create git tag
git tag v1.1.0

# 4. Push to GitHub
git push origin main
git push origin v1.1.0

# This triggers GitHub Actions to build and publish

Version Display

Health Endpoint

The version is exposed via the health endpoint:

curl http://localhost:3005/api/health

# Response includes:
{
  "version": "1.0.0",
  "gitCommit": "abc123",
  ...
}

Docker Image Inspection

# View image labels
docker inspect sasha-studio:latest | grep -A5 Labels

# View all tags
docker images sasha-studio

Build Information

After each build, a .last-build.json file is created with build details:

{
  "version": "1.0.0",
  "buildDate": "2024-01-11T10:00:00Z",
  "gitCommit": "abc123",
  "gitBranch": "main",
  "gitStatus": "clean",
  "tags": ["sasha-studio:1.0.0", "sasha-studio:latest"],
  "target": "runner"
}

Best Practices

Version Bumping Guidelines

PATCH - Bug fixes, security updates, dependency updates
```
./scripts/version.sh patch
```
MINOR - New features, non-breaking changes
```
./scripts/version.sh minor
```
MAJOR - Breaking changes, major refactors
```
./scripts/version.sh major
```

Pre-release Workflow

# Start beta phase
./scripts/version.sh prerelease beta

# Test and iterate
./scripts/version.sh prerelease beta  # -> beta.2, beta.3, etc.

# Move to release candidate
./scripts/version.sh prerelease rc

# Final release
./scripts/version.sh set 1.1.0

Development Builds

For development builds with uncommitted changes:

The build script automatically detects "dirty" state
Creates a unique dev tag with timestamp and commit
Example: 1.0.0-dev.20240111-143022.abc123

Registry Management

Local Registry

# Run local registry
docker run -d -p 5000:5000 --name registry registry:2

# Tag and push
docker tag sasha-studio:1.0.0 localhost:5000/sasha-studio:1.0.0
docker push localhost:5000/sasha-studio:1.0.0

GitHub Container Registry

# Set registry environment variable
export DOCKER_REGISTRY=ghcr.io/yourusername

# Build and push
./claudecodeui/scripts/docker-build.sh production

Rollback Strategy

Quick Rollback

# List available versions
docker images sasha-studio --format "table {{.Tag}}\t{{.Created}}"

# Run specific version
docker run -p 3005:3005 sasha-studio:1.0.0

Version History

Keep track of deployed versions:

# Tag production deployments
docker tag sasha-studio:1.0.0 sasha-studio:prod-20240111

# View deployment history
docker images sasha-studio | grep prod-

Troubleshooting

Common Issues

Version Mismatch

# Sync package.json with VERSION file
./scripts/version.sh current

Build Cache Issues

# Clear Docker build cache
docker builder prune -a

Tag Conflicts

# Force retag
docker tag -f sasha-studio:new sasha-studio:latest

Version Verification

# Check VERSION file
cat VERSION

# Check package.json
grep version claudecodeui/package.json

# Check running container
curl http://localhost:3005/api/health | jq .version

# Check Docker image
docker inspect sasha-studio:latest | grep -i version

Migration from Old System

If migrating from an unversioned system:

Determine current version based on features
Create VERSION file: echo "1.0.0" > VERSION
Tag existing images: docker tag sasha-studio:latest sasha-studio:1.0.0
Update CI/CD pipelines to use new versioning
Document version history in CHANGELOG.md

Changelog

Maintain a CHANGELOG.md file documenting version changes:

# Changelog

## [1.1.0] - 2024-01-11
### Added
- Semantic versioning system
- Automated Docker tagging
- Version display in health endpoint

### Changed
- Enhanced build scripts with version support
- Updated CI/CD workflows

### Fixed
- Build reproducibility issues

Summary

The semantic versioning system provides:

Consistent version management
Automated Docker tagging
Clear version history
Easy rollback capability
CI/CD integration
Development/production separation
Build metadata tracking

For questions or issues, refer to the build scripts in claudecodeui/scripts/ or check the .last-build.json file for build details.