{"id":34675203,"url":"https://github.com/hatlabs/container-packaging-tools","last_synced_at":"2026-02-09T12:17:06.986Z","repository":{"id":323750504,"uuid":"1094427760","full_name":"hatlabs/container-packaging-tools","owner":"hatlabs","description":"Tooling for generating Debian packages from container application definitions","archived":false,"fork":false,"pushed_at":"2026-01-01T18:45:45.000Z","size":932,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-02T02:25:10.845Z","etag":null,"topics":["apt-package","halos"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hatlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-11T17:36:08.000Z","updated_at":"2026-01-01T18:39:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hatlabs/container-packaging-tools","commit_stats":null,"previous_names":["hatlabs/container-packaging-tools"],"tags_count":86,"template":false,"template_full_name":null,"purl":"pkg:github/hatlabs/container-packaging-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatlabs%2Fcontainer-packaging-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatlabs%2Fcontainer-packaging-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatlabs%2Fcontainer-packaging-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatlabs%2Fcontainer-packaging-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hatlabs","download_url":"https://codeload.github.com/hatlabs/container-packaging-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hatlabs%2Fcontainer-packaging-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28853196,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-28T15:15:36.453Z","status":"ssl_error","status_checked_at":"2026-01-28T15:15:13.020Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apt-package","halos"],"created_at":"2025-12-24T20:26:23.363Z","updated_at":"2026-01-28T22:03:30.429Z","avatar_url":"https://github.com/hatlabs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Container Packaging Tools\n\nCommand-line tools for converting container application definitions into Debian packages.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![CI](https://github.com/hatlabs/container-packaging-tools/actions/workflows/pr.yml/badge.svg)](https://github.com/hatlabs/container-packaging-tools/actions/workflows/pr.yml)\n\n## Overview\n\n`container-packaging-tools` automates the creation of Debian packages from simple container app definitions. It transforms Docker Compose configurations, metadata, and configuration schemas into production-ready Debian packages with systemd integration, eliminating the need to understand Debian packaging internals.\n\n### Key Features\n\n- **Automated Package Generation**: Convert app definitions to complete Debian packages\n- **CasaOS Converter**: Import applications from CasaOS app store format\n- **Template-Based**: Uses Jinja2 templates for all packaging files\n- **Comprehensive Validation**: Validates metadata, Docker Compose, and configuration schemas\n- **systemd Integration**: Automatically generates systemd service units\n- **Cockpit Ready**: Generates web UI metadata for Cockpit integration\n- **AppStream Support**: Creates AppStream metadata for software centers\n- **Standards Compliant**: Follows Debian packaging standards and best practices\n\n### Use Cases\n\n- Package marine applications (Signal K, OpenCPN, AvNav) for HaLOS\n- Create container-based Debian packages for any Docker application\n- Standardize packaging across multiple applications\n- Automate CI/CD pipelines for container app deployment\n\n## Requirements\n\n- **Debian 13 (Trixie) or newer** - Required for Python 3.11+ and Pydantic v2.0+\n- **Raspberry Pi OS** (Trixie-based) is also supported\n- **Ubuntu 24.04+** or other Debian-based distributions with compatible package versions\n\n**Note:** Older distributions like Ubuntu 22.04 or Debian 12 (Bookworm) do not have Pydantic v2.0+ available in their repositories.\n\n## Agentic Coding Setup (Claude Code, GitHub Copilot, etc.)\n\nFor development with AI assistants, use the halos-distro workspace for full context:\n\n```bash\n# Clone the workspace\ngit clone https://github.com/hatlabs/halos-distro.git\ncd halos-distro\n\n# Get all sub-repositories including container-packaging-tools\n./run repos:clone\n\n# Work from workspace root for AI-assisted development\n# Claude Code gets full context across all repos\n```\n\nSee `halos-distro/docs/` for development workflows:\n- `LIFE_WITH_CLAUDE.md` - Quick start guide\n- `IMPLEMENTATION_CHECKLIST.md` - Development checklist\n- `DEVELOPMENT_WORKFLOW.md` - Detailed workflows\n\n## Installation\n\n```bash\n# From APT repository (when available)\nsudo apt install container-packaging-tools\n\n# Or build from source\ngit clone https://github.com/hatlabs/container-packaging-tools.git\ncd container-packaging-tools\n./run build\nsudo dpkg -i ../container-packaging-tools_*.deb\n```\n\n## Quick Start\n\n### 1. Create Your App Definition\n\nCreate a directory with three required files:\n\n```bash\nmkdir my-app\ncd my-app\n```\n\n**metadata.yaml** - Package metadata:\n```yaml\nname: My Web Application\npackage_name: my-app-container\nversion: 1.0.0\nupstream_version: 1.0.0\ndescription: A simple web application\nlong_description: |\n  This is my container application packaged as a Debian package.\nhomepage: https://example.com/my-app\nmaintainer: Your Name \u003cyour.email@example.com\u003e\nlicense: MIT\ntags:\n  - role::container-app\n  - implemented-in::docker\ndebian_section: web\narchitecture: all\n\nweb_ui:\n  enabled: true\n  path: /\n  port: 8080\n  protocol: http\n\ndefault_config:\n  APP_PORT: \"8080\"\n  LOG_LEVEL: \"info\"\n```\n\n**docker-compose.yml** - Container definition:\n```yaml\nversion: '3.8'\n\nservices:\n  app:\n    image: nginx:alpine\n    container_name: my-app\n    ports:\n      - \"${APP_PORT:-8080}:80\"\n    environment:\n      - LOG_LEVEL=${LOG_LEVEL:-info}\n    volumes:\n      - /var/lib/container-apps/my-app-container/data:/usr/share/nginx/html:rw\n    restart: \"no\"\n```\n\n\u003e **Note: Non-Root Containers**\n\u003e If your container runs as a non-root user (like Grafana UID 472), add `user: \"472\"` to docker-compose.yml. This ensures the tool generates correct directory ownership in the postinst script. See [EXAMPLES.md - Pattern 6](EXAMPLES.md#pattern-6-non-root-container-with-volume-permissions) for details.\n\n**config.yml** - Configuration schema:\n```yaml\nversion: \"1.0\"\ngroups:\n  - id: general\n    label: General Settings\n    description: Basic application configuration\n    fields:\n      - id: APP_PORT\n        label: Application Port\n        type: integer\n        default: 8080\n        required: true\n        min: 1024\n        max: 65535\n        description: Port for the web interface\n\n      - id: LOG_LEVEL\n        label: Log Level\n        type: enum\n        default: info\n        required: false\n        options: [debug, info, warning, error]\n        description: Logging verbosity\n```\n\n### 2. Generate and Build the Package\n\n```bash\n# Generate Debian package structure\ngenerate-container-packages my-app/ build/\n\n# Build the Debian package\ncd build/my-app-container\ndpkg-buildpackage -us -uc\n\n# Install the package\nsudo dpkg -i ../my-app-container_1.0.0_all.deb\n```\n\n### 3. Manage Your Application\n\n```bash\n# Start the service\nsudo systemctl start my-app-container\n\n# Check status\nsudo systemctl status my-app-container\n\n# View logs\nsudo journalctl -u my-app-container -f\n\n# Access the web interface\ncurl http://localhost:8080/\n\n# Configure the application\nsudo nano /etc/container-apps/my-app-container/env\nsudo systemctl restart my-app-container\n```\n\nFor more examples and detailed documentation, see [EXAMPLES.md](EXAMPLES.md).\n\n## CasaOS Converter\n\nThe CasaOS converter allows you to import applications from the CasaOS app store format and convert them to the container-packaging-tools format. This is useful for leveraging the large CasaOS app ecosystem.\n\n### Converting CasaOS Applications\n\n```bash\n# Convert a single CasaOS app definition\ngenerate-container-packages convert-casaos casaos-app.yml output/\n\n# Convert in batch mode (entire directory)\ngenerate-container-packages convert-casaos --batch casaos-apps/ output/\n\n# Convert with asset download (icons, screenshots)\ngenerate-container-packages convert-casaos --download-assets casaos-app.yml output/\n\n# Sync mode - only update changed files\ngenerate-container-packages convert-casaos --batch --sync casaos-apps/ output/\n```\n\n### Conversion Features\n\n- **Automatic Mapping**: Converts CasaOS metadata to container-packaging-tools format\n- **Category Translation**: Maps CasaOS categories to Debian package sections\n- **Field Type Detection**: Intelligently converts configuration field types\n- **Asset Download**: Optional download of icons and screenshots\n- **Batch Processing**: Convert multiple apps in parallel\n- **Sync Mode**: Only update files when source has changed (preserves manual edits to generated files, skips unchanged conversions)\n\n### Example Workflow\n\n```bash\n# 1. Clone a CasaOS app store\ngit clone https://github.com/IceWhaleTech/CasaOS-AppStore.git\n\n# 2. Convert CasaOS apps to container-packaging-tools format\ngenerate-container-packages convert-casaos --batch \\\n  CasaOS-AppStore/Apps/ \\\n  converted-apps/\n\n# 3. Review and customize converted apps (optional)\n# The converter creates metadata.yaml, docker-compose.yml, and config.yml\n# You can manually edit these files before packaging\nls converted-apps/*/\n\n# 4. Generate Debian package structures and build .deb files\nfor app in converted-apps/*/; do\n  generate-container-packages \"$app\" build/\n  cd \"build/$(basename \"$app\")\" \u0026\u0026 dpkg-buildpackage -us -uc \u0026\u0026 cd ../..\ndone\n\n# The .deb files are now in build/\nls -lh build/*.deb\n```\n\nFor detailed converter documentation, see the converter module documentation.\n\n## Documentation\n\n- **[EXAMPLES.md](EXAMPLES.md)** - Comprehensive examples and usage patterns\n- **[docs/SPEC.md](docs/SPEC.md)** - Technical specification and requirements\n- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - System architecture and design\n- **[docs/DESIGN.md](docs/DESIGN.md)** - High-level design documentation\n\n## Input Format\n\nEach application definition directory must contain:\n\n| File | Required | Description |\n|------|----------|-------------|\n| `metadata.yaml` | Yes | Package metadata (name, version, description, etc.) |\n| `docker-compose.yml` | Yes | Docker Compose configuration |\n| `config.yml` | Yes | User-configurable parameters schema |\n| `icon.png` or `icon.svg` | No | Application icon |\n| `screenshot*.png` | No | Screenshots for AppStream metadata |\n\n## Output Structure\n\nThe tool generates a complete Debian package structure:\n\n```\n\u003cpackage-name\u003e/\n├── debian/\n│   ├── control           # Package metadata\n│   ├── rules             # Build rules\n│   ├── install           # File installation\n│   ├── postinst          # Post-installation script\n│   ├── prerm             # Pre-removal script\n│   ├── postrm            # Post-removal script\n│   ├── changelog         # Package changelog\n│   ├── copyright         # License information\n│   └── compat            # Debhelper compatibility\n├── systemd/\n│   └── service           # systemd service unit\n├── appstream/\n│   └── metainfo.xml      # AppStream metadata\n└── files/\n    ├── docker-compose.yml\n    ├── config.yml\n    └── env.template       # Environment file template\n```\n\n## Development\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/hatlabs/container-packaging-tools.git\ncd container-packaging-tools\n\n# Build the development Docker container\n./run docker:build\n\n# Run tests\n./run test\n\n# Run linter\n./run lint\n\n# Check formatting\n./run format:check\n\n# Run type checker\n./run typecheck\n```\n\n### Testing\n\nAll development happens in Docker containers to ensure consistent Debian Trixie environment:\n\n```bash\n# Run all tests\n./run test\n\n# Run specific test categories\n./run test:unit                    # Unit tests only\n./run test:integration             # Integration tests only\n\n# Run with coverage\n./run test:coverage                # Requires 80% coverage\n\n# Open interactive shell\n./run docker:shell\n```\n\n### Pre-commit Hooks\n\nThis project uses [lefthook](https://github.com/evilmartians/lefthook) for pre-commit hooks to run lint checks locally before commits.\n\n```bash\n# Install lefthook (one-time)\nbrew install lefthook\n\n# Enable hooks in this repo\n./run hooks-install\n```\n\n**What it checks:**\n\n- `ruff check src/ tests/` - Linting\n\n**Skip hooks when needed:**\n\n```bash\ngit commit --no-verify -m \"WIP: message\"\n```\n\n### Code Quality\n\nBefore submitting changes, ensure all checks pass:\n\n```bash\n# Run all quality checks\n./run check\n\n# Individual checks\n./run lint              # Ruff linter\n./run format            # Code formatting\n./run typecheck         # Type checking with ty\n```\n\n### Local Development (Non-Docker)\n\nFor faster iteration on Debian/Ubuntu systems:\n\n```bash\n# Install build dependencies\nsudo apt install dpkg-dev debhelper dh-python python3-all\n\n# Install Python dependencies\nuv sync --dev\n\n# Run tests locally\nuv run pytest\n\n# Note: Some tests require dpkg-buildpackage and will fail on non-Debian systems\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run all quality checks (`./run check`)\n5. Run all tests (`./run test`)\n6. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/)\n7. Push to your branch\n8. Open a Pull Request\n\n### Development Workflow\n\n- All commits must follow conventional commit format\n- PRs must have passing CI checks before merge\n- Code coverage must be maintained at 80% or higher\n- All code must pass linting, formatting, and type checking\n\n## Related Projects\n\n- **[halos-marine-containers](https://github.com/hatlabs/halos-marine-containers)** - Marine application definitions using this tool\n- **[halos-distro](https://github.com/hatlabs/halos-distro)** - HaLOS workspace and distribution\n- **[cockpit-apt](https://github.com/hatlabs/cockpit-apt)** - APT package manager for Cockpit\n- **[halos-pi-gen](https://github.com/hatlabs/halos-pi-gen)** - HaLOS image builder\n\n## License\n\nMIT License - see [debian/copyright](debian/copyright) for full details.\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/hatlabs/container-packaging-tools/issues)\n- **Documentation**: [EXAMPLES.md](EXAMPLES.md) and [docs/](docs/)\n- **HaLOS Project**: [hatlabs.github.io/halos](https://hatlabs.github.io/halos)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhatlabs%2Fcontainer-packaging-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhatlabs%2Fcontainer-packaging-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhatlabs%2Fcontainer-packaging-tools/lists"}