Skip to content

svnstfns/scale-api-compose-pilot

Repository files navigation

Scale API Compose Pilot

CI/CD PyPI version Python 3.8+ License: MIT Code style: black Ruff mypy

Pilot Docker Compose workloads to TrueNAS Scale via WebSocket API - AI-friendly automation tool.

Features

  • 🐳 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

Installation

📦 Quick Install

# 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

Quick Start

🚀 Automatic Setup (Recommended)

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

Manual Setup (Optional)

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"
}

CLI Usage

# 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

Python Library Usage

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())

Docker Compose Support

Supported Features

  • ✅ Container images
  • ✅ Port forwarding
  • ✅ Environment variables
  • ✅ Volume mounts
  • ✅ Restart policies

Limitations

  • ❌ Multi-service compose files (single service only)
  • ❌ Custom networks
  • ❌ Build contexts
  • ❌ Secrets and configs

Example Compose File

services:
  webapp:
    image: nginx:latest
    ports:
      - "8080:80"
    environment:
      - ENV=production
    volumes:
      - /host/data:/var/www/html
    restart: unless-stopped

API Reference

TrueNASDockerManager

Methods

  • connect() - Establish WebSocket connection
  • authenticate() - Authenticate with API key
  • list_apps() - Get all installed apps
  • get_app_details(app_name) - Get specific app details
  • create_app(app_config) - Create new app
  • start_app(app_name) - Start an app
  • stop_app(app_name) - Stop an app
  • delete_app(app_name) - Delete an app
  • deploy_compose_stack(file_path, app_name) - Deploy Docker Compose
  • close() - Close connection

Context Manager

async with TrueNASDockerManager() as manager:
    # Automatically connects and authenticates
    apps = await manager.list_apps()
    # Automatically closes connection

Error Handling

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}")

Development

Setup Development Environment

git clone https://github.com/svnstfns/scale-api-compose-pilot.git
cd scale-api-compose-pilot
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black scale_api_compose_pilot/

Type Checking

mypy scale_api_compose_pilot/

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Run the test suite
  6. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

0.1.0 (2024-12-22)

  • Initial release
  • Basic Docker Compose support
  • CLI interface
  • WebSocket API integration
  • Async context manager support

Requirements

  • Python 3.8+
  • TrueNAS Scale (Electric Eel or later)
  • Valid TrueNAS API key

🚀 TOP 5 Community-Requested Features

Based on extensive research of TrueNAS forums, Reddit, and GitHub issues, here are the most requested features that Scale API Compose Pilot addresses:

1. ✅ Direct Docker Compose Support

"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

2. 🔄 Multi-Container Stack Support (Planned)

"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

3. 📁 Simplified Storage Management

"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

4. 🌐 Easy Network Configuration

"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

5. 🔧 Migration from K3s/Portainer

"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

Bonus Features Users Love:

  • 🤖 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

Troubleshooting

Connection Issues

  1. Verify TrueNAS is accessible: ping your-truenas-host
  2. Check API key validity in TrueNAS web interface
  3. Ensure WebSocket endpoint is accessible: curl -k wss://your-truenas-host/websocket

Docker Compose Issues

  1. Ensure single-service compose files
  2. Use official Docker images (no build contexts)
  3. Check volume path permissions

Common Errors

  • TrueNASConnectionError: Check host and network connectivity
  • TrueNASAuthenticationError: Verify API key
  • DockerComposeError: Validate compose file format

For more help, see the documentation or open an issue.

About

Pilot Docker Compose workloads to TrueNAS Scale via WebSocket API - AI-friendly automation tool

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages