Scale API Compose Pilot
Pilot Docker Compose workloads to TrueNAS Scale via WebSocket API - AI-friendly automation tool.
- 🐳 Docker Compose Support: Deploy Docker Compose stacks to TrueNAS Scale
- 🔌 WebSocket API: Uses TrueNAS Scale's modern WebSocket API (Electric Eel)
- 🛠️ CLI Interface: Easy-to-use command-line tool
- 📦 Python Library: Programmatic access for automation
- 🔒 Authentication: Secure API key authentication
- 🔄 App Management: Start, stop, delete, and update apps
# Install from PyPI (when published)
pip install scale-api-compose-pilot
# Or install from source
git clone https://github.com/svnstfns/scale-api-compose-pilot.git
cd scale-api-compose-pilot
pip install -e .
Note: The TrueNAS API client will be automatically installed if needed. If automatic installation fails, you can manually install it:
pip install git+https://github.com/truenas/api_client.git
The easiest way to get started is with our interactive setup wizard:
scale-compose init
This will:
- 🔍 Auto-discover TrueNAS systems on your network
- 🔑 Guide you through API key creation
- ✅ Validate your connection
- 💾 Save your configuration
If you prefer manual configuration, create a .env
file:
TRUENAS_HOST=your-truenas-host.local
TRUENAS_API_KEY=your-api-key-here
Or use the config file at ~/.scale-compose
:
{
"truenas_host": "your-truenas-host.local",
"api_key": "your-api-key-here"
}
# List all apps
scale-compose list
# Deploy a Docker Compose stack
scale-compose deploy ./docker-compose.yml my-app
# Start/stop apps
scale-compose start my-app
scale-compose stop my-app
# Delete an app
scale-compose delete my-app --force
import asyncio
from scale_api_compose_pilot import TrueNASDockerManager
async def main():
# Using environment variables
async with TrueNASDockerManager() as manager:
# List apps
apps = await manager.list_apps()
print(f"Found {len(apps)} apps")
# Deploy Docker Compose
await manager.deploy_compose_stack(
'./docker-compose.yml',
'my-app'
)
# Or with explicit credentials
async def with_credentials():
manager = TrueNASDockerManager(
host="truenas.local",
api_key="your-api-key"
)
await manager.connect()
await manager.authenticate()
try:
apps = await manager.list_apps()
print(f"Found {len(apps)} apps")
finally:
await manager.close()
asyncio.run(main())
- ✅ Container images
- ✅ Port forwarding
- ✅ Environment variables
- ✅ Volume mounts
- ✅ Restart policies
- ❌ Multi-service compose files (single service only)
- ❌ Custom networks
- ❌ Build contexts
- ❌ Secrets and configs
services:
webapp:
image: nginx:latest
ports:
- "8080:80"
environment:
- ENV=production
volumes:
- /host/data:/var/www/html
restart: unless-stopped
connect()
- Establish WebSocket connectionauthenticate()
- Authenticate with API keylist_apps()
- Get all installed appsget_app_details(app_name)
- Get specific app detailscreate_app(app_config)
- Create new appstart_app(app_name)
- Start an appstop_app(app_name)
- Stop an appdelete_app(app_name)
- Delete an appdeploy_compose_stack(file_path, app_name)
- Deploy Docker Composeclose()
- Close connection
async with TrueNASDockerManager() as manager:
# Automatically connects and authenticates
apps = await manager.list_apps()
# Automatically closes connection
The library provides specific exception types:
from scale_api_compose_pilot import (
TrueNASConnectionError,
TrueNASAuthenticationError,
TrueNASAPIError,
DockerComposeError
)
try:
async with TrueNASDockerManager() as manager:
await manager.deploy_compose_stack('./compose.yml', 'app')
except TrueNASConnectionError:
print("Failed to connect to TrueNAS")
except TrueNASAuthenticationError:
print("Invalid API key")
except DockerComposeError:
print("Invalid Docker Compose file")
except TrueNASAPIError as e:
print(f"TrueNAS API error: {e}")
git clone https://github.com/svnstfns/scale-api-compose-pilot.git
cd scale-api-compose-pilot
pip install -e ".[dev]"
pytest
black scale_api_compose_pilot/
mypy scale_api_compose_pilot/
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Run the test suite
- Submit a pull request
MIT License - see LICENSE file for details.
- Initial release
- Basic Docker Compose support
- CLI interface
- WebSocket API integration
- Async context manager support
- Python 3.8+
- TrueNAS Scale (Electric Eel or later)
- Valid TrueNAS API key
Based on extensive research of TrueNAS forums, Reddit, and GitHub issues, here are the most requested features that Scale API Compose Pilot addresses:
"I just want to upload my docker-compose.yml"
- Problem: TrueNAS requires manual YAML editing with advanced knowledge
- Our Solution:
scale-compose deploy ./docker-compose.yml my-app
- one command deployment - Status: ✅ Fully implemented
"How do I deploy apps with multiple containers?"
- Problem: TrueNAS treats each container as a separate app
- Our Solution: Automatic splitting and network configuration for related services
- Status: 🚧 In roadmap - currently single-service only
"IX volumes vs bind mounts is confusing"
- Problem: Complex storage patterns, permission issues
- Our Solution: Automatic conversion of named volumes to IX volumes, smart bind mount detection
- Status: ✅ Implemented with intelligent path validation
"I can't figure out macvlan vs bridge networking"
- Problem: Networking complexity, port conflicts
- Our Solution: Auto-detection of network requirements, clear guidance on bridge vs macvlan
- Status: ✅ Basic implementation, enhanced detection coming
"How do I migrate my apps after the Docker update?"
- Problem: Breaking changes in TrueNAS 24.10 (Electric Eel)
- Our Solution: Import existing compose files, automatic conversion to new format
- Status: ✅ Compose import works, full migration tools planned
- 🤖 AI-Friendly Interface: Structured responses for automation
- ⚡ WebSocket API: Using TrueNAS's modern API (not deprecated REST)
- 🔒 Secure Authentication: API key-based auth without shell access
- 📊 Real-time Status: Live app monitoring and management
- Verify TrueNAS is accessible:
ping your-truenas-host
- Check API key validity in TrueNAS web interface
- Ensure WebSocket endpoint is accessible:
curl -k wss://your-truenas-host/websocket
- Ensure single-service compose files
- Use official Docker images (no build contexts)
- Check volume path permissions
TrueNASConnectionError
: Check host and network connectivityTrueNASAuthenticationError
: Verify API keyDockerComposeError
: Validate compose file format
For more help, see the documentation or open an issue.