Packager Overview

The Packager app is your personal package creation studio for building and managing custom application distributions in HomeDock OS. Introduced in version 2.0.2.144, Packager enables you to create shareable .hds packages that can be distributed and installed across any HomeDock OS instance, making them instantly available in the App Store.

With Packager, we’ve liberalized the App Store. Anyone can now privately include custom packages within their HomeDock OS App Store, making it perfect for rapid deployments, sharing applications with friends, or even distributing packages through GitHub. Your App Store, your rules.

This update exists for one reason only. The community. Welcome to the new era of HomeDock OS application distribution.

Overview

Packager introduces the HDS Package Management System, a specialized format designed to simplify application distribution across HomeDock OS instances. With Packager, you can bundle Docker Compose files with custom icons, metadata, and configurations into a single, portable package.

_{Packager democratizes the App Store by letting you create, import, and manage your own custom packages without requiring official approval or centralized distribution.}

Features

Packager operates in two main modes accessible through tabs:

Package Generator

Create new .hds packages from scratch with the Package Generator interface.

Required Files

Docker Compose File Required

• Upload a .yml or .yaml Docker Compose file
• Automatic image detection from compose file
• Built-in compose editor for making changes
• Supports single and multi-service applications
• Maximum file size: 10 MB

Tip

The system automatically detects the Docker image and version from your compose file, which you can then use to auto-fill the Docker Image and Version fields.

App Icon Required

• Upload a .jpg or .png image for your application
• Real-time preview of uploaded icon
• Recommended size: 512x512 pixels or larger
• Maximum file size: 5 MB
• Supports JPG and PNG formats with magic byte verification for security

Package Metadata

All fields marked with Required must be filled:

App Slug Required

• Unique identifier for your package (e.g., my-awesome-app)
• Must be lowercase with dashes instead of spaces
• Used for filenames and internal identification
• Format validation ensures slug compatibility

App Name Required

• Display name shown to users (e.g., “My Awesome App”)
• This is the pretty name users will see in the App Store
• Can contain spaces, capitals, and special characters

Category Required

• Select from predefined categories:
  • Media
  • Files & Productivity
  • Networking
  • Home & Automation
  • Social
  • Gaming
  • Security
  • Development
  • Databases
  • Monitoring
  • Other
• Helps users find your app in the App Store

Type Required

• Brief classification of your app (e.g., “Media Server”, “Development Tool”)
• Displayed as a subtitle in the App Store

Docker Image Required

• The Docker image name (e.g., myuser/myapp)
• Can be auto-filled from detected compose file
• Exclude the tag/version from this field

Version Required

• Image version/tag (e.g., latest, 1.2.3, stable)
• Can be auto-filled from detected compose file
• Used for update detection

Author Required

• Your name or organization
• Displayed in package details
• Credits the package creator

Description Required

• Concise description of what the application does
• Maximum 130 characters
• Shown in the App Store listing

Advanced Features

DevHook Placeholders

Packager supports dynamic variables in compose files that are automatically replaced during installation:

User & Authentication

• [[HD_USER_NAME]]: HomeDock OS username (automatically filled from system)
• [[HD_PASSWORD]]: Simple randomly generated password in format word_word_1234 (e.g., apple_banana_4567)
• [[HD_SYSTEM_PASSWORD]]: Secure 20-character alphanumeric password for system-level auth
• [[HD_RND_STR]]: Random 16-character string (useful for API keys, tokens, secrets)

Network & Connectivity

• [[HD_LOCAL_IP]]: Local network IP address of the HomeDock OS instance
• [[HD_INTERNET_IP]]: Public/internet IP address (if any)
• [[HD_DYN_DNS]]: Dynamic DNS hostname configured in Settings (Deprecated but still available as we will be rolling out our own Dynamic DNS BIND9*DDNS solution in Q4 2026)

Storage Paths

• [[INSTALL_PATH]]: AppData directory path (e.g., /DATA/HomeDock/AppData on Linux)
• [[APP_MOUNT_POINT]]: AppFolders directory path (e.g., /DATA/HomeDock/AppFolders on Linux)

Tip

DevHook placeholders are cross-platform and automatically adapt to the underlying OS (Linux, macOS, Windows). Use them to create portable packages that work seamlessly across all HomeDock OS installations.

Compose Editor

• Click “Edit Compose” to open the built-in editor
• Syntax validation ensures your compose file is valid
• Live preview of changes
• Formatting assistance for proper YAML structure

Package Creation

• Click “Create & Download .hds Package” to generate your package
• All fields are validated before creation
• Package downloads automatically as a .hds file
• Maximum package size: 5 MB

_{The Package Generator validates every field and file before creation, ensuring your .hds package is properly formatted and ready for distribution.}

Caution

Ensure all required fields are filled and both the Docker Compose file and icon are uploaded. The create button will be disabled until all requirements are met.

Package Manager

Import, browse, and manage all your custom application packages in one place.

Import Packages

Upload .hds Package

• Drag and drop or click to upload .hds files
• Automatic validation checks ensure package integrity
• Security verification of file contents
• Package signature validation (256-bit .hds_signature)
• Automatic installation to your package library

Import Workflow

1. Select or drag a .hds package file
2. System validates package format and contents
3. Package is extracted and files are verified
4. Icon, compose file, and metadata are installed
5. Package becomes immediately available in the App Store

_{Imported packages appear instantly in your App Store alongside official applications, ready to install with the same familiar interface.}

Package Management

View Installed Packages

• Browse all imported custom packages
• View package metadata and details
• See installation status and version

Edit Packages

• Modify existing package metadata
• Update icons or compose files
• Change descriptions and categories

Delete Packages

• Remove packages from your library
• Automatic cleanup of associated files
• Icons and compose configurations are removed

Package Storage

Custom packages are organized in the _user_packages/ directory:

_user_packages/
├── my-app.hds          # Package file
├── icons/
│   └── my-app.jpg      # Package icon
└── compose/
    └── my-app.yml      # Docker Compose file

Security Features

Packager implements multiple security layers:

File Type Validation

• Magic byte verification for uploaded files
• Whitelist-based validation (HDS for packages, YAML for compose, JPG/PNG for icons)
• Dangerous pattern detection blocking potentially harmful code

Package Integrity

• 256-bit .hds_signature for tamper detection
• Content validation on import
• Path traversal protection during extraction

Size Limits

• Package files: 5 MB maximum
• Compose files: 10 MB maximum
• Icons: 5 MB maximum

_{Packager implements multiple security layers including magic byte verification, signature validation, and content checking to ensure safe package distribution.}

Note

While the .hds_signature should prevent tampering, content validation adds an extra security layer. The signature can theoretically be recalculated by an attacker, so content validation ensures safety.

App Store Integration

Packages created with Packager seamlessly integrate with the App Store:

• Unified Interface: Custom packages appear alongside official HomeDock OS apps
• Same Features: Install, update, and manage custom packages like any other app
• Update Detection: Automatic detection when newer package versions are available
• Desktop Icons: Custom packages get proper icons with theme-aware styling

Installation Workflow

Custom packages support the same installation features as official apps:

• Advanced configuration options
• Port and volume customization
• Network settings configuration
• Environment variables
• Capabilities management

Best Practices

Creating Packages

1. Test Your Compose File: Ensure it works correctly before packaging
2. Use Clear Names: Make slugs and display names descriptive
3. Write Good Descriptions: Help users understand what your app does
4. Choose Appropriate Icons: Use high-quality, recognizable images
5. Select Correct Category: Makes your app easier to discover
6. Version Properly: Use semantic versioning for better update tracking

Managing Packages

1. Keep Packages Updated: Regularly update packages with new versions
2. Document Changes: Maintain changelogs for your packages
3. Backup Packages: Keep copies of your .hds files for redistribution
4. Test After Import: Verify packages work correctly after importing

Versioning Support

The .hds format includes version tracking:

• Format Version: Ensures compatibility across HomeDock OS releases
• App Version: Tracks the application version inside the package
• Update Detection: System compares versions for update notifications

Sharing Packages

.hds packages are portable and can be shared:

1. Export Package: Download the .hds file after creation
2. Share File: Distribute via email, cloud storage, or repositories
3. Import on Other Instances: Recipients can import using Package Manager
4. Automatic Setup: Package installs with all metadata and configurations intact

_{Share your .hds packages on GitHub, distribute them to your team, or keep them private for rapid deployments across your own HomeDock OS instances.}

Mobile Optimization

Packager is fully responsive:

• Touch-Friendly: Optimized layouts for tablets and phones
• Responsive Inputs: Form controls adapt to screen size
• Mobile Upload: Drag-and-drop works on mobile browsers that support it

Theme Support

Packager supports all HomeDock OS themes:

• Default: Clean, professional interface for package creation
• Noir: Dark mode for comfortable late-night packaging
• Aero+: Modern aesthetic with backdrop effects

Technical Details

Package Format

• .hds files are specialized archives containing metadata, icons, and compose files
• Includes validation checksums and signatures
• Platform-independent for cross-system compatibility

Docker Compose Helper

• Standardized utilities for parsing and validating compose files
• Automatic image and tag extraction
• Multi-service application support

Cache Invalidation

• Package changes reflect immediately throughout the interface
• No need to refresh after importing or creating packages

_{Packager democratizes application distribution in HomeDock OS, making it simple for anyone to create, share, and install custom applications across the platform without centralized gatekeeping.}