Checkpoints

Checkpoints allow you to capture the complete state of an environment at a point in time, enabling quick rollbacks, environment cloning, and disaster recovery.

Overview

A checkpoint captures:

Container state - Running processes and memory state
File system - All files and directories
Database state - Data and schema
Configuration - Environment variables and settings
Network state - Active connections and routing

Note

Checkpoints use incremental snapshots, so subsequent checkpoints of the same environment are faster and use less storage.

Creating Checkpoints

Basic Checkpoint

# Create a checkpoint
teabar checkpoint create my-feature-env

# Create with a name
teabar checkpoint create my-feature-env --name "before-migration"

# Create with description
teabar checkpoint create my-feature-env 
  --name "pre-release-v2" 
  --description "State before v2.0 release deployment"

Output:

Creating checkpoint for environment: my-feature-env

Capturing state...
  ✓ Container state captured
  ✓ File system captured (2.3 GB)
  ✓ Database state captured (450 MB)
  ✓ Configuration captured

Checkpoint created successfully!

  ID:          chk_abc123xyz
  Name:        before-migration
  Environment: my-feature-env
  Size:        2.75 GB
  Created:     2024-01-15 14:32:01 UTC

To restore: teabar checkpoint restore chk_abc123xyz

Automatic Checkpoints

Configure automatic checkpoint creation:

# teabar.yaml
checkpoints:
  auto:
    enabled: true
    schedule: "0 0 * * *"  # Daily at midnight
    retention: 7           # Keep last 7 automatic checkpoints
    
  # Create checkpoint before deployments
  before_deploy: true
  
  # Create checkpoint before destructive operations
  before_delete: true

Checkpoint Hooks

Create checkpoints at specific events:

# teabar.yaml
hooks:
  pre_deploy:
    - teabar checkpoint create ${ENV_NAME} --name "pre-deploy-${DEPLOY_ID}"
  
  post_deploy:
    - teabar checkpoint create ${ENV_NAME} --name "post-deploy-${DEPLOY_ID}"

Listing Checkpoints

# List all checkpoints
teabar checkpoint list

# List checkpoints for specific environment
teabar checkpoint list --env my-feature-env

# List with details
teabar checkpoint list --verbose

# Filter by date
teabar checkpoint list --since 7d

Output:

Checkpoints

ID              NAME              ENVIRONMENT      SIZE    CREATED
chk_abc123xyz   before-migration  my-feature-env   2.75GB  2024-01-15 14:32:01
chk_def456uvw   post-deploy-v1    my-feature-env   2.71GB  2024-01-14 10:15:00
chk_ghi789rst   auto-daily        my-feature-env   2.68GB  2024-01-14 00:00:00
chk_jkl012mno   pre-deploy-v1     my-feature-env   2.65GB  2024-01-13 16:45:00

Total: 4 checkpoints, 10.79 GB

Viewing Checkpoint Details

teabar checkpoint show chk_abc123xyz

Output:

{
  "id": "chk_abc123xyz",
  "name": "before-migration",
  "description": "State before database migration",
  "environment": {
    "id": "env_xyz789",
    "name": "my-feature-env",
    "project": "frontend"
  },
  "created_at": "2024-01-15T14:32:01Z",
  "created_by": "[email protected]",
  "size": {
    "total": "2.75 GB",
    "breakdown": {
      "containers": "1.2 GB",
      "filesystem": "1.1 GB",
      "database": "450 MB"
    }
  },
  "components": [
    {"name": "web", "type": "container", "size": "600 MB"},
    {"name": "api", "type": "container", "size": "600 MB"},
    {"name": "postgres", "type": "database", "size": "450 MB"},
    {"name": "redis", "type": "cache", "size": "50 MB"}
  ],
  "metadata": {
    "git_commit": "abc123",
    "git_branch": "feature/new-dashboard",
    "blueprint_version": "1.2.0"
  }
}

Restoring from Checkpoints

Basic Restore

# Restore to checkpoint (replaces current state)
teabar checkpoint restore chk_abc123xyz

Warning

Restoring a checkpoint replaces the current environment state. A checkpoint of the current state is automatically created before restoration.

Restore Options

# Restore to the same environment
teabar checkpoint restore chk_abc123xyz

# Skip automatic pre-restore checkpoint
teabar checkpoint restore chk_abc123xyz --no-backup

# Restore specific components only
teabar checkpoint restore chk_abc123xyz --components database,cache

Restore Workflow

1. Pre-restore validation
   ↓
2. Create backup checkpoint (unless --no-backup)
   ↓
3. Stop running components
   ↓
4. Restore filesystem state
   ↓
5. Restore database state
   ↓
6. Restore configuration
   ↓
7. Start components
   ↓
8. Verify health checks
   ↓
9. Complete

Comparing Checkpoints

Compare two checkpoints to see what changed:

teabar checkpoint diff chk_abc123xyz chk_def456uvw

Output:

Checkpoint Comparison
From: chk_abc123xyz (before-migration)
To:   chk_def456uvw (post-deploy-v1)

Configuration Changes:
  + ENV_VAR_NEW=value
  ~ DATABASE_URL=...new-value (was: ...old-value)
  - DEPRECATED_VAR

File Changes:
  Modified: 23 files
  Added:    5 files
  Deleted:  2 files
  
  Notable changes:
    M /app/src/api/routes.js (+45, -12)
    M /app/package.json (+3, -1)
    A /app/src/api/new-endpoint.js
    D /app/src/api/deprecated.js

Database Changes:
  Tables modified: users, orders
  Rows changed: +1,234 -56
  Schema changes: Added column 'users.preferences'

Size Difference: +40 MB (2.71 GB -> 2.75 GB)

Managing Storage

Checkpoint Retention

# teabar.yaml
checkpoints:
  retention:
    # Keep checkpoints for 30 days
    max_age: 30d
    
    # Keep at least 5 checkpoints regardless of age
    min_count: 5
    
    # Maximum storage per environment
    max_storage: 50GB
    
    # Never delete checkpoints with these tags
    preserve_tags:
      - production
      - release

Manual Cleanup

# Delete a specific checkpoint
teabar checkpoint delete chk_abc123xyz

# Delete checkpoints older than 30 days
teabar checkpoint prune --older-than 30d

# Delete all but the last 5 checkpoints
teabar checkpoint prune --keep 5

# Dry run to see what would be deleted
teabar checkpoint prune --older-than 30d --dry-run

Storage Usage

# View checkpoint storage usage
teabar checkpoint storage

# View by environment
teabar checkpoint storage --env my-feature-env

Output:

Checkpoint Storage Usage

Organization Total: 125.4 GB

By Project:
  frontend        45.2 GB (36%)
  backend         38.7 GB (31%)
  data-pipeline   25.8 GB (21%)
  infrastructure  15.7 GB (12%)

By Environment (top 5):
  staging              12.3 GB  (8 checkpoints)
  production           10.5 GB  (5 checkpoints)
  my-feature-env        8.2 GB  (4 checkpoints)
  testing               7.8 GB  (12 checkpoints)
  demo                  6.4 GB  (3 checkpoints)

Checkpoint Tags

Organize checkpoints with tags:

# Add tags when creating
teabar checkpoint create my-feature-env 
  --name "release-v2.0" 
  --tags release,production,v2.0

# Add tags to existing checkpoint
teabar checkpoint tag chk_abc123xyz --add important,keep

# Remove tags
teabar checkpoint tag chk_abc123xyz --remove temporary

# List checkpoints by tag
teabar checkpoint list --tag release

Exporting and Importing

Export Checkpoint

# Export checkpoint to file
teabar checkpoint export chk_abc123xyz --output checkpoint.tar.gz

# Export to S3
teabar checkpoint export chk_abc123xyz --output s3://my-bucket/checkpoints/

Import Checkpoint

# Import from file
teabar checkpoint import checkpoint.tar.gz --env my-feature-env

# Import from S3
teabar checkpoint import s3://my-bucket/checkpoints/checkpoint.tar.gz

API Access

# Use OIDC token (from teabar auth or Keycloak service account)
# List checkpoints via API
curl -H "Authorization: Bearer $TEABAR_TOKEN" 
  "https://api.teabar.dev/v1/checkpoints?environment=my-feature-env"

# Create checkpoint via API
curl -X POST 
  -H "Authorization: Bearer $TEABAR_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{"name": "api-checkpoint", "environment": "my-feature-env"}' 
  "https://api.teabar.dev/v1/checkpoints"

Best Practices

Name checkpoints meaningfully - Use descriptive names like “pre-migration” or “release-v2.0”
Create before risky operations - Always checkpoint before migrations or major changes
Use tags for organization - Tag important checkpoints to prevent accidental deletion
Set retention policies - Avoid storage bloat with automatic cleanup
Test restores regularly - Verify checkpoints work by restoring to test environments
Export critical checkpoints - Back up important checkpoints to external storage

Note

Checkpoint creation typically takes 30-60 seconds for small environments and 2-5 minutes for larger ones.

Troubleshooting

Checkpoint Creation Fails

# Check available storage
teabar checkpoint storage

# Check environment status
teabar env status my-feature-env

# View checkpoint agent logs
teabar logs my-feature-env --component checkpoint-agent

Restore Fails

# Verify checkpoint integrity
teabar checkpoint verify chk_abc123xyz

# Check for compatibility issues
teabar checkpoint restore chk_abc123xyz --dry-run

# Restore with verbose logging
teabar checkpoint restore chk_abc123xyz --verbose

Slow Checkpoint Operations

Large databases can slow checkpoint creation
Use --exclude to skip large temporary files
Consider using database-native backup tools for very large databases

# Exclude temporary files
teabar checkpoint create my-feature-env 
  --exclude "/tmp/*" 
  --exclude "/var/log/*" 
  --exclude "*.log"