Registry Integration¶
The TFGrid Compose registry allows you to discover and deploy apps by name, without manually cloning repositories.
:::info Version Registry integration was added in v0.10.0 (October 15, 2025) :::
Quick Start¶
# Search available apps
tfgrid-compose search
# Deploy an app by name
tfgrid-compose up wordpress
# List deployed apps
tfgrid-compose list
# Switch between apps
tfgrid-compose switch ai-agent
Searching Apps¶
Browse All Apps¶
Output:
Available apps:
ai-agent AI-powered deployment assistant
wordpress WordPress CMS platform
nextcloud File sharing and collaboration
ghost Modern blogging platform
discourse Community discussion forum
...
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. ✅ 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:
The asterisk (*) indicates the currently active app.
Switch Active App¶
Change which app commands operate on:
After switching:
- tfgrid-compose logs → shows ai-agent logs
- tfgrid-compose status → shows ai-agent status
- tfgrid-compose exec → runs commands on ai-agent
Context-Aware Commands¶
Once you switch, all commands operate on the active app:
# Switch to WordPress
tfgrid-compose switch wordpress
# These all operate on WordPress now
tfgrid-compose logs
tfgrid-compose status
tfgrid-compose address
# Switch to AI agent
tfgrid-compose switch ai-agent
# Now these operate on ai-agent
tfgrid-compose exec login
tfgrid-compose logs
Complete Workflow Example¶
Deploy Multiple Apps¶
# Search for apps
tfgrid-compose search
# Deploy WordPress blog
tfgrid-compose up wordpress
# Deploy AI agent for development
tfgrid-compose up ai-agent
# Deploy Nextcloud for file storage
tfgrid-compose up nextcloud
# List all deployed apps
tfgrid-compose list
Output:
Work with Different Apps¶
# Work with AI agent
tfgrid-compose switch ai-agent
tfgrid-compose exec create my-project
tfgrid-compose exec run my-project
tfgrid-compose logs
# Check WordPress status
tfgrid-compose switch wordpress
tfgrid-compose address
tfgrid-compose logs
# Manage Nextcloud
tfgrid-compose switch nextcloud
tfgrid-compose status
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¶
wordpress:
description: WordPress CMS platform
repo: https://github.com/tfgrid-studio/wordpress-app
pattern: gateway
tags:
- cms
- blog
- php
ai-agent:
description: AI-powered deployment assistant
repo: https://github.com/tfgrid-studio/tfgrid-ai-agent
pattern: single-vm
tags:
- ai
- development
- tools
Registry Location¶
Public registry: https://github.com/tfgrid-studio/registry
Advanced Usage¶
Mix Registry and Local Apps¶
# Deploy from registry
tfgrid-compose up wordpress
# Deploy from local path
tfgrid-compose up ./my-custom-app
# Both work together
tfgrid-compose list
Output:
Deploy Same App Multiple Times¶
# Deploy production WordPress from registry
tfgrid-compose up wordpress
# Deploy staging WordPress from local fork
tfgrid-compose up ./wordpress-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 wordpress
tfgrid-compose up wordpress
# Option 2: Switch to it
tfgrid-compose switch wordpress
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