Containr/docs/superpowers/specs/2026-04-14-compose-template-catalog-design.md

Compose Template Catalog Design

Context

Containr templates must work like a CasaOS-style app catalog for a self-hosted platform. Templates are pure Docker Compose files. Users can import public or connected GitHub repositories, paste Compose YAML manually, review app metadata/screenshots, fill setup variables, and install into a project with a short path from catalog to running services.

Decisions

• Docker Compose YAML is the template source of truth. No containr.template.json manifest is required.
• Valid Compose extension fields under x-containr may provide catalog metadata:
  • name
  • description
  • category
  • icon
  • screenshots
  • developer
  • tagline
• If metadata is absent, Containr derives sensible defaults from the Compose file path, repository name, and Compose services map.
• Variables are discovered from Compose placeholders such as ${BASE_URL} and ${PORT:-8080}.
• GitHub import supports connected GitHub providers and public GitHub URLs/repositories. Manual import supports pasting raw Docker Compose YAML.
• The catalog shows app cards with description, screenshots, service count, source metadata, and an install action.
• Install opens a quick setup flow: select/create project, review Compose services, fill variables, then create one Containr service per Compose service.

Data Model

service_templates stores:

• existing catalog fields: name, description, category, logo, variables, source fields
• raw Compose YAML in compose_yaml
• screenshots as JSON in screenshots
• parsed Compose summary in config, including service names, images, build contexts, ports, commands, and environment keys

The raw Compose YAML stays available for future full-stack redeploys even when the current service model only maps a subset of Compose fields.

Backend Flow

GitHub import:

1. Resolve repository and branch from repo_full_name, GitHub URL, or provider repository selection.
2. Find Compose file path from user input or defaults: docker-compose.yml, docker-compose.yaml, compose.yml, compose.yaml.
3. Fetch raw YAML using the connected provider token when provided, or public GitHub API access otherwise.
4. Parse metadata, services, screenshots, and variables.
5. Store a community template with source_type = github.

Manual import:

1. Accept raw Compose YAML and optional source URL/name override.
2. Parse and validate at least one Compose service.
3. Store a community template with source_type = manual.

Install:

1. Validate project ownership.
2. Substitute user-provided variables into supported service fields.
3. Create services for every Compose service.
4. Audit the install with template ID, source, and created service IDs.

Frontend Flow

The Templates page becomes a catalog:

• Browse/search/filter templates.
• Cards show icon, description, screenshots preview, source, and service count.
• Import from GitHub supports connected provider selection plus manual GitHub URL/repo/path entry.
• Paste Compose accepts raw YAML in a large text area, CasaOS-style.
• Install opens a quick setup panel with project selection, service review, variable form, screenshots, and source link.

Testing

• TypeScript build must pass.
• Focused backend packages must pass.
• Browser smoke checks Projects, Templates catalog, paste/import entry points, monitoring-only Usage, and project canvas rendering.