Registry Integration¶
The TFGrid Compose registry allows you to discover and deploy apps by name, without manually cloning repositories.
:::info Version Registry integration is available in v0.13.4 (current version) :::
Quick Start¶
# Search available apps
tfgrid-compose search
# Deploy an app by name
tfgrid-compose up tfgrid-ai-agent
# List deployed apps
tfgrid-compose ps
# Switch between apps
tfgrid-compose switch tfgrid-ai-agent
Searching Apps¶
Browse All Apps¶
Output:
Available apps:
tfgrid-ai-agent AI coding assistant with Qwen integration
tfgrid-gitea Self-hosted Git service with web interface
Search by Name¶
Output:
Search by Keyword¶
Output:
Deploying Apps¶
Deploy by Name¶
Instead of cloning repositories manually, deploy directly by name:
What happens: 1. ✅ Fetches app info from registry 2. ✅ Downloads app repository to cache 3. ✅ Deploys the app (4 CPU, 8GB RAM, 100GB disk VM) 4. ✅ Sets it as active context
Deploy from Local Path¶
You can still deploy from local paths:
Both methods work identically - the CLI automatically detects whether you're providing a name or path.
Managing Multiple Apps¶
List Deployed Apps¶
See all your deployed apps:
Output:
CONTAINER ID APP NAME STATUS IP ADDRESS CONTRACT SOURCE AGE
────────────────────────────────────────────────────────────────────────────────
a5dd5e8846d6abac wordpress active 185.69.167.160 1745517 registry 4m ago
The asterisk (*) indicates the currently active app.
Switch Active App¶
Change which app commands operate on:
After switching:
tfgrid-compose logs→ shows ai-agent logstfgrid-compose status→ shows ai-agent statustfgrid-compose exec→ runs commands on ai-agent
Context-Aware Commands¶
Once you switch, all commands operate on the active app:
# Switch to AI agent
tfgrid-compose switch tfgrid-ai-agent
# These all operate on AI agent now
tfgrid-compose logs
tfgrid-compose status
tfgrid-compose create my-project
# Switch to Gitea
tfgrid-compose switch tfgrid-gitea
# Now these operate on Gitea
tfgrid-compose address
tfgrid-compose logs
Complete Workflow Example¶
Deploy Multiple Apps¶
# Search for apps
tfgrid-compose search
# Deploy AI agent for development
tfgrid-compose up tfgrid-ai-agent
# Deploy Gitea for code storage
tfgrid-compose up tfgrid-gitea
# List all deployed apps
tfgrid-compose ps
Work with Different Apps¶
# Work with AI agent
tfgrid-compose switch tfgrid-ai-agent
tfgrid-compose create my-project
tfgrid-compose monitor my-project
tfgrid-compose logs
# Check Gitea status
tfgrid-compose switch tfgrid-gitea
tfgrid-compose address
tfgrid-compose logs
App Caching¶
Apps are automatically cached locally for fast deployment.
Cache Location¶
~/.config/tfgrid-compose/
├── registry/
│ └── apps.yaml # Registry cache (1hr TTL)
├── apps/
│ ├── wordpress/ # Cached app repos
│ ├── ai-agent/
│ └── nextcloud/
├── state/
│ ├── wordpress/ # Per-app deployment state
│ ├── ai-agent/
│ └── nextcloud/
└── current-app # Active app pointer
Cache Behavior¶
- Registry: Refreshed every hour automatically
- Apps: Downloaded once, reused for all deployments
- Updates: Apps use cached version (pull updates manually if needed)
Updating Cached Apps¶
# Navigate to cached app
cd ~/.config/tfgrid-compose/apps/wordpress
# Pull latest changes
git pull
# Redeploy with updates
tfgrid-compose up wordpress
State Management¶
Each app has isolated state, preventing conflicts.
Per-App State¶
# Deploy two apps
tfgrid-compose up wordpress
tfgrid-compose up nextcloud
# Each has independent state
~/.config/tfgrid-compose/state/
├── wordpress/
│ ├── vm_ip
│ ├── wireguard.conf
│ └── ansible_inventory.yaml
└── nextcloud/
├── vm_ip
├── wireguard.conf
└── ansible_inventory.yaml
No Conflicts¶
You can deploy the same app multiple times by deploying from different paths with different names.
Comparison: Old vs New¶
Old Way (Pre-v0.10.0)¶
# Manual steps
git clone https://github.com/tfgrid-studio/wordpress-app
cd wordpress-app
tfgrid-compose up .
New Way (v0.10.0+)¶
Registry Format¶
The registry is a simple YAML file hosted on GitHub.
Example Registry Entry¶
tfgrid-ai-agent:
description: AI coding assistant with Qwen integration
repo: https://github.com/tfgrid-studio/tfgrid-ai-agent
pattern: single-vm
version: v0.3.0
tags:
- ai
- coding
- development
- qwen
requirements:
cpu: 4
memory: 8GB
disk: 100GB
tfgrid-gitea:
description: Self-hosted Git service with web interface
repo: https://github.com/tfgrid-studio/tfgrid-gitea
pattern: single-vm
version: v1.0.0
tags:
- git
- scm
- repository
- collaboration
requirements:
cpu: 2
memory: 4GB
disk: 50GB
Registry Location¶
Public registry: https://github.com/tfgrid-studio/registry
Advanced Usage¶
Mix Registry and Local Apps¶
# Deploy from registry
tfgrid-compose up tfgrid-ai-agent
# Deploy from local path
tfgrid-compose up ./my-custom-app
# Both work together
tfgrid-compose ps
Deploy Same App Multiple Times¶
# Deploy production AI agent from registry
tfgrid-compose up tfgrid-ai-agent
# Deploy staging AI agent from local fork
tfgrid-compose up ./ai-agent-staging
Troubleshooting¶
App Not Found¶
Solution: Search the registry to find the correct name:
Cache Issues¶
If the registry seems outdated, it refreshes automatically after 1 hour. To force refresh:
# Remove cache
rm -rf ~/.config/tfgrid-compose/registry/
# Next command will fetch fresh registry
tfgrid-compose search
App Already Deployed¶
Solution: Destroy first or switch to it:
# Option 1: Destroy and redeploy
tfgrid-compose down tfgrid-ai-agent
tfgrid-compose up tfgrid-ai-agent
# Option 2: Switch to it
tfgrid-compose switch tfgrid-ai-agent
Best Practices¶
1. Search Before Deploying¶
Always search to find the right app name:
2. List Regularly¶
Keep track of deployed apps:
3. Switch Explicitly¶
Always switch before running commands:
4. Clean Up Unused Apps¶
Destroy apps you're no longer using:
Next Steps¶
Related¶
TFGrid Studio Ecosystem
Integrated tools and resources