Operations

This document explains Composia's task system, resource management, and common operational tasks.

Task System

Overview

Composia uses a task queue to manage all asynchronous operations:

Controller is responsible for task creation and status management
Agents actively pull tasks belonging to them via long-polling
Tasks report status, logs, and results step by step

Task Types

Task Type	Description	Trigger
`deploy`	Deploy service	Manual/API
`update`	Update service	Manual/API
`stop`	Stop service	Manual/API
`restart`	Restart service	Manual/API
`backup`	Execute backup	Manual/API
`dns_update`	Update DNS records	Automatic/Manual
`caddy_sync`	Sync Caddy configuration	Automatic
`caddy_reload`	Reload Caddy	Automatic
`prune`	Clean up resources	Manual/API
`migrate`	Migrate service	Manual/API

Task Lifecycle

Created → Pending → Running → Completed
                    │
                    ├─► Failed
                    │
                    └─► Cancelled

Viewing Tasks

Web UI:

Tasks page shows all tasks
Filter by service, node, type, status
Click task to view detailed logs

Task Status:

Status	Description
Pending	Waiting for Agent to pull
Running	Currently executing
Success	Execution successful
Failed	Execution failed
Cancelled	Cancelled

Task Logs

Real-time logs are output during task execution:

[2024-01-15 10:30:00] Starting deployment of service my-app to node main
[2024-01-15 10:30:01] Downloading service bundle...
[2024-01-15 10:30:05] Rendering runtime directory...
[2024-01-15 10:30:06] Executing docker compose up -d
[2024-01-15 10:30:15] Container started successfully
[2024-01-15 10:30:16] Syncing Caddy configuration...
[2024-01-15 10:30:18] Deployment completed

Docker Resource Management

Container Management

Agents regularly report Docker container information from nodes, and Controller provides a unified browsing interface.

Viewing Containers:

Navigate to Containers page
Filter containers by node
View container status, image, ports, etc.

Container Operations:

Operation	Description
View Logs	View container logs in real-time
Start	Start a stopped container
Stop	Stop a running container
Restart	Restart container
Terminal	Enter container to execute commands

Viewing Container Logs:

# In Web UI
1. Find target container
2. Click **Logs** button
3. View real-time or search historical logs

Container Terminal:

bash

# Web UI provides basic terminal functionality
1. Click **Terminal** button on container
2. Select shell (bash/sh)
3. Execute commands

Image Management

Viewing Images:

Images page shows all images on all nodes
Displays image tags, size, creation time

Cleaning Images:

bash

# Manually clean unused images
curl -X POST http://localhost:7001/api/v1/nodes/main/prune \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "images"}'

Network Management

Viewing Networks:

Networks page shows Docker networks
View network driver, subnet, connected containers

Volume Management

Viewing Volumes:

Volumes page shows Docker volumes
View volume size, mount points

Node Management

Node Status

Agents send heartbeats every 5 seconds containing:

Information	Description
Online Status	Whether connected to Controller
Docker Version	Node Docker version
Container Count	Number of running containers
Resource Usage	CPU, memory, disk usage
Service Instances	List of service instances on this node

Node Views

Web UI provides the following views:

Node List: Overview of all nodes
Node Detail: Detailed information and resource usage of a single node
Service Instances: Service deployment status on nodes
Dashboard: Overall resource usage trends

Node Operations

Reconnect Agent:

If Agent disconnects:

Check Agent container logs
Check network connectivity
Restart Agent container

bash

docker compose restart agent

Resource Cleanup

Cleanup Tasks

Execute prune tasks to clean up unused resources:

Web UI:

Navigate to Nodes page
Select target node
Click Clean button
Select resource types to clean

API:

bash

# Clean unused containers
curl -X POST http://localhost:7001/api/v1/nodes/main/prune \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "containers"}'

# Clean unused images
curl -X POST http://localhost:7001/api/v1/nodes/main/prune \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "images"}'

# Clean unused volumes
curl -X POST http://localhost:7001/api/v1/nodes/main/prune \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "volumes"}'

# Clean all
curl -X POST http://localhost:7001/api/v1/nodes/main/prune \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "all"}'

Auto-Cleanup Recommendations

Set up scheduled tasks for regular cleanup:

bash

# Cron example (daily cleanup at 3 AM)
0 3 * * * curl -X POST http://localhost:7001/api/v1/nodes/main/prune \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"type": "images"}'

Log Management

Task Logs

Task logs are stored in Controller's log_dir:

log_dir/
├── tasks/
│   ├── 2024-01-15/
│   │   ├── task-001.log
│   │   └── task-002.log
│   └── 2024-01-16/
│       └── task-003.log

Container Logs

Container logs are retrieved in real-time via Docker API; historical logs are managed by Docker.

Log Retention Policy

Recommended log rotation configuration:

yaml

# docker-compose.yaml
services:
  controller:
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "5"

Monitoring and Alerting

Current Monitoring Capabilities

Real-time Status: Web UI displays service, container, and node status in real-time
Resource Usage: Node CPU, memory, disk usage
Log Viewing: Real-time container and task logs

Troubleshooting

Common Issues

1. Agent Cannot Connect to Controller

Check:

Is Controller address correct?
Do Tokens match?
Network connectivity
Firewall settings

2. Deployment Failed

Check:

Error messages in task logs
Docker Compose file syntax
Is image pullable?
Port conflicts

3. Service Status Inconsistent

Check:

Is Agent online?
Are containers actually running?
Are labels correctly set?

4. Caddy Configuration Not Applied

Check:

Caddy infrastructure service status
Configuration fragment syntax
Agent directory mounts

Debug Mode

Enable debug logging:

bash

# Controller
LOG_LEVEL=debug go run ./cmd/composia controller ...

# Agent
LOG_LEVEL=debug go run ./cmd/composia agent ...

Getting Support

View GitHub Issues
Refer to Development Guide
Check log files

Performance Optimization

Controller Optimization

Use SSD storage for state_dir
Regularly clean old task logs
Set appropriate pull_interval

Agent Optimization

Ensure smooth Docker socket access
Monitor Agent resource usage
Regularly clean unused resources

Database Optimization

SQLite performance optimization:

sql

-- Regularly execute VACUUM
VACUUM;

-- Check database integrity
PRAGMA integrity_check;

Deployment — Service deployment operations
Backup & Migration — Data protection operations
Networking — DNS and proxy configuration

Operations ​

Task System ​

Overview ​

Task Types ​

Task Lifecycle ​

Viewing Tasks ​

Task Logs ​

Docker Resource Management ​

Container Management ​

Image Management ​

Network Management ​

Volume Management ​

Node Management ​

Node Status ​

Node Views ​

Node Operations ​

Resource Cleanup ​

Cleanup Tasks ​

Auto-Cleanup Recommendations ​

Log Management ​

Task Logs ​

Container Logs ​

Log Retention Policy ​

Monitoring and Alerting ​

Current Monitoring Capabilities ​

Recommended Monitoring Solutions ​

Troubleshooting ​

Common Issues ​

Debug Mode ​

Getting Support ​

Performance Optimization ​

Controller Optimization ​

Agent Optimization ​

Database Optimization ​

Related Documentation ​

Operations

Task System

Overview

Task Types

Task Lifecycle

Viewing Tasks

Task Logs

Docker Resource Management

Container Management

Image Management

Network Management

Volume Management

Node Management

Node Status

Node Views

Node Operations

Resource Cleanup

Cleanup Tasks

Auto-Cleanup Recommendations

Log Management

Task Logs

Container Logs

Log Retention Policy

Monitoring and Alerting

Current Monitoring Capabilities

Recommended Monitoring Solutions

Troubleshooting

Common Issues

Debug Mode

Getting Support

Performance Optimization

Controller Optimization

Agent Optimization

Database Optimization

Related Documentation