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.

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 .hds package, or combine multiple packages into a .hdstore bundle for bulk distribution. You can also generate App Store badges to promote your apps on websites, READMEs, and social media.

_{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 a segmented control:

Package Generator

Create new .hds packages from scratch. To generate a package you need to provide:

• Docker Compose file: A .yml or .yaml file (max 10 MB). The system automatically detects the Docker image and version from it. A built-in editor lets you modify the compose file before packaging.
• App Icon: A .jpg or .png image, ideally 512x512px or larger (max 5 MB). Validated via magic bytes for security.

Package Metadata

Field	Example	Notes
App Slug	my-awesome-app	Lowercase with dashes. Spaces become dashes, underscores are not allowed, consecutive dashes collapse automatically.
App Name	My Awesome App	Display name shown in the App Store.
Category	Media, Development, Gaming…	Select from predefined categories (Media, Files & Productivity, Networking, Home & Automation, Social, Gaming, Security, Development, Databases, Monitoring, Other).
Type	Media Server	Brief classification shown as subtitle.
Docker Image	myuser/myapp	Image name without tag. Can be auto-filled from compose.
Version	latest, 1.2.3	Image tag. Can be auto-filled from compose.
Author	Your Name	Credits the package creator.
Description	A fast media server	Max 130 characters. Shown in the App Store listing.

DevHook Placeholders

Compose files support dynamic variables that are automatically replaced during installation:

• [[HD_USER_NAME]]: HomeDock OS username.
• [[HD_PASSWORD]]: Random password in format word_word_1234 (e.g., apple_banana_4567).
• [[HD_SYSTEM_PASSWORD]]: Secure 20-character alphanumeric password.
• [[HD_RND_STR]]: Random 16-character string for API keys, tokens, or secrets.
• [[HD_LOCAL_IP]]: Local network IP address.
• [[HD_INTERNET_IP]]: Public/internet IP address.
• [[HD_DYN_DNS]]: Dynamic DNS hostname. (Deprecated, own BIND9/DDNS solution coming Q4 2026)
• [[INSTALL_PATH]]: AppData directory (e.g., /DATA/HomeDock/AppData on Linux).
• [[APP_MOUNT_POINT]]: AppFolders directory (e.g., /DATA/HomeDock/AppFolders on Linux).
• [[SSL_CERT_PATH]]: SSL certificates directory. Linux: /DATA/SSLCerts, macOS: /Users/{username}/HomeDock/SSLCerts, Windows: /mnt/c/HomeDock/SSLCerts.

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.

Once all fields are filled, click “Create & Download .hds Package” to validate and download the package (max 5 MB).

Caution

The create button remains disabled until all required fields are filled and both the Docker Compose file and icon are uploaded.

Package Manager

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

Importing .hds Packages

Drag and drop or click to upload a .hds file. The system validates the package format, verifies the 256-bit .hds_signature, extracts the contents, and installs the icon, compose file, and metadata. The package becomes immediately available in the App Store alongside official apps.

Bulk Export & Import with .hdstore

The .hdstore format bundles multiple .hds packages into a single file, useful for migrating your custom app library to another instance, sharing a curated collection, or creating backups.

• Export: Select the packages you want, click Export as .hdstore, and download a single file with all of them. For example, bundle plex, radarr, and sonarr into media-stack.hdstore and share your entire media server setup in one file.
• Preview: Before importing, you can preview the contents of a .hdstore to verify which packages are included.
• Import: Upload the .hdstore, review the bundled packages, and confirm, all packages are extracted, validated, and installed at once.

Note

.hdstore files support up to 300 packages per bundle with a maximum file size of 75 MB.

Managing Packages

From the Package Manager you can browse all your imported packages, edit their metadata, icons, or compose files, and delete packages you no longer need (associated files are cleaned up automatically).

App Store Badges

Generate downloadable SVG badges to promote your apps on websites, READMEs, or social media. Badges are generated 100% client-side, no backend required. Click any variant to download it instantly as {app-slug}-badge-{theme}.svg.

Custom App Badges

Per-app badges that feature your app’s icon, a “Get {AppName}” call-to-action, and HomeDock OS branding. The SVG is fully self-contained (icon embedded as base64), so it renders anywhere without external dependencies. Available in light and dark themes.

Examples:

Generic Branding Badges

Universal badges not tied to a specific app, similar to Apple’s “Download on the App Store” badges. Available in light and dark variants.

Examples:

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 (.hds): 5 MB maximum
• Package bundles (.hdstore): 75 MB maximum (up to 300 packages)
• 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 and .hdstore bundles are portable and can be shared:

1. Export: Download individual .hds files or bundle multiple packages into a single .hdstore
2. Share: Distribute via email, cloud storage, GitHub, or any file hosting service
3. Promote: Generate App Store badges to link to your packages from your website or README
4. Import on Other Instances: Recipients import using Package Manager, single packages or entire bundles
5. Automatic Setup: Packages install with all metadata, icons, and configurations intact

_{Share your .hds packages on GitHub, distribute them to your team, promote them with App Store badges, 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 Formats

• .hds files are specialized archives containing metadata, icons, and compose files
• .hdstore files are zip bundles containing multiple .hds packages with shared metadata, designed for bulk distribution and migration
• Both formats include 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.}