Container Platform Standard¶

v1.3 | Build 004.20260815.172533Z

Standard for the McGuckin.Net container platform.

NET-003

Container Platform Standard

Phase 1 - Platform Foundation

JUKEBOX PLATFORM STORAGE MODEL

Owner: Todd McGuckin | Applies To: JUKEBOX | Status: Draft

Document Control¶

Revision History¶

Contents¶

Phase 1 - Platform Foundation

Step 1.1 - Environment Overview

Step 1.2 - Storage Standards

Step 1.3 - Container Platform Standards

Step 1.4 - Networking Standards

Step 1.5 - Backup and Recovery

Step 1.6 - Operational Standards

Step 1.7 - Platform Design Principles

Appendix A - Definitions

Phase 1 - Platform Foundation¶

Phase 1 establishes the architecture and operating rules required before production container workloads are migrated to JUKEBOX. It defines where the platform lives, how application state is preserved, how services are deployed, and how the environment is operated and recovered.

Step 1.1 - Environment Overview¶

A. Purpose¶

The purpose of this standard is to create a predictable, recoverable, and maintainable container platform on JUKEBOX. It establishes a common deployment model so that future services can be added without redesigning the platform each time.

B. Scope¶

This standard governs containerized workloads deployed on JUKEBOX, including platform services, user-facing services, monitoring components, and future media-automation services. It governs storage placement, Compose organization, Docker networking, backup expectations, and day-to-day operational behavior.

This standard does not define organization-wide naming, DNS, reverse proxy, security, logging, monitoring, or update policies. Those subjects will be governed by separate infrastructure standards.

C. Hardware and Software Baseline¶

D. Current Volume Inventory¶

* Available capacity observed from Finder on 2026-08-15. Values will change with use.

E. Assumptions¶

• JUKEBOX operates as a dedicated, continuously available server.

• The PlexDB SSD remains continuously attached and available before Docker starts.

• The Storage array remains continuously attached and retains its existing SoftRAID/HFS+ design.

• The Backups and TARDIS volumes remain attached and available for their scheduled backup operations.

• Docker Desktop remains the container runtime for the current single-host platform.

Completion Criteria¶

• Hardware and software baseline documented.

• Scope and exclusions approved.

• Storage volumes identified and mounted consistently.

• Operating assumptions confirmed.

Step 1.2 - Storage Standards¶

A. Separation of Storage Responsibilities¶

JUKEBOX uses five distinct volumes for the operating system, application state, media content, non-Time Machine recovery data, and Apple Time Machine protection. This separation reduces recovery complexity and prevents growth in one workload from consuming capacity intended for another.

B. PlexHD - Operating System and Applications¶

PlexHD is the startup SSD and remains responsible for macOS and installed applications. Docker Desktop itself shall remain installed on PlexHD because it is a macOS application managed with the rest of the operating environment.

C. PlexDB - Platform and Application State¶

PlexDB is the designated SSD for native Plex metadata and all persistent Docker platform state. It provides the performance characteristics and free capacity required for databases, configuration files, logs, scripts, and Docker runtime state. Backup copies required for catastrophic recovery belong on the independent Backups volume.

Directory model status: The directory listing below is retained from v0.2 and remains under review. This volume-inventory revision does not approve or implement changes to the end-state file tree.

/Volumes/PlexDB/Docker

appdata/ Persistent application data

compose/ Compose project definitions

backups/ Application and platform backups

configs/ Shared platform configuration

logs/ Centralized platform logs when required

scripts/ Maintenance and recovery scripts

secrets/ Externalized secret files

templates/ Approved deployment templates

D. Storage - Media and Downloads¶

The Storage volume remains the authoritative location for downloads, media libraries, and unsorted content. Its existing HFS+ filesystem is retained because the SoftRAID implementation was designed around that filesystem and is currently functioning reliably.

E. Backups - Non-Time Machine Recovery Data¶

The Backups volume is the independent destination for non-Time Machine recovery data required to reconstruct JUKEBOX after a catastrophic failure. Its protected backup set shall include approved configuration files, Compose recipes and environment definitions, application-native exports, platform scripts, documentation, and other rebuild assets. It shall not host live application data or Docker runtime state.

F. TARDIS - Apple Time Machine¶

TARDIS is the exclusive Apple Time Machine destination for JUKEBOX. It shall not host Docker runtime state, live application data, or the independent non-Time Machine recovery set maintained on Backups.

G. Docker Desktop Virtual Machine Storage¶

Docker Desktop maintains a Linux virtual-machine disk that can grow substantially as images, layers, and volumes accumulate. The Docker Desktop application remains on PlexHD, but its virtual-machine disk should be relocated to PlexDB.

Completion Criteria¶

• /Volumes/PlexDB/Docker created.

• Standard Docker subdirectories created.

• Docker Desktop virtual-machine disk relocated to PlexDB.

• Existing Storage directory structure left unchanged.

• Read/write access verified for all required bind-mount paths.

Step 1.3 - Container Platform Standards¶

A. Deployment Model¶

Each application shall be deployed as an independent Compose project. This keeps upgrades, rollback, troubleshooting, and service ownership isolated while still allowing related containers to be grouped when they form one logical application.

B. Compose Directory Structure¶

Compose projects shall be stored beneath /Volumes/PlexDB/Docker/compose using one directory per application. Environment-specific values may be stored in a project-local .env file.

compose/

portainer/

compose.yaml

.env

homepage/

compose.yaml

.env

sonarr/

compose.yaml

.env

C. Persistent Data¶

Containers are runtime instances and may be removed or recreated without warning. Application state must therefore remain outside the container filesystem in bind-mounted directories under AppData.

D. AppData Organization¶

Each application shall receive a dedicated directory beneath /Volumes/PlexDB/Docker/appdata. Directory names shall correspond to the logical application name used by the Compose project.

E. Compose File Name¶

F. Service Re-creation¶

A service shall be considered recoverable when its container can be deleted and recreated from the Compose definition while retaining application configuration and data through externalized persistent storage.

Completion Criteria¶

• One-project-per-application structure approved.

• compose.yaml naming standard adopted.

• AppData directory pattern created.

• Test container successfully removed and recreated without data loss.

• No required configuration stored only inside a container filesystem.

Step 1.4 - Networking Standards¶

A. Network Separation¶

Docker networks provide controlled service-to-service communication and reduce unnecessary exposure. The initial platform design uses functional networks rather than placing every service on a single shared network.

B. Service Exposure¶

C. Future Compatibility¶

The initial networking model shall not prevent later adoption of a reverse proxy, split-horizon DNS, or additional container hosts. Those features are not configured by this phase and will be governed by separate standards.

Completion Criteria¶

• frontend, backend, and monitoring networks defined.

• Each Phase 2 service assigned only to required networks.

• Unnecessary host-port publication avoided.

• Container-to-container name resolution tested.

Step 1.5 - Backup and Recovery¶

A. Layered Backup Strategy¶

No single backup mechanism is sufficient for the platform. JUKEBOX shall use complementary backup layers so that individual applications, the Docker platform, the host, and the complete service environment can be recovered at the appropriate level.

B. Recovery Objective¶

A complete platform recovery should require installation of macOS and Docker Desktop, restoration of native application exports, Compose definitions, Docker application data, and the native Plex application-data tree from the local Backups volume or the immutable Backblaze B2 copy, reconnection of Storage, and orderly redeployment of services. Routine application settings should not require manual reconstruction.

C. Backup Scope¶

• /Volumes/PlexDB/Docker/compose

• /Volumes/PlexDB/Docker/appdata

• /Volumes/PlexDB/Docker/scripts

• /Volumes/PlexDB/Docker/configs

• Application-native export locations

• Documentation required to rebuild Docker Desktop and reconnect storage

• /Volumes/PlexDB/Plex (complete native Plex application-data tree; media libraries remain excluded)

• /Volumes/Backups/Application-Exports

• /Volumes/Backups/Platform-Recovery

• /Volumes/Backups/Host-Recovery

• /Volumes/Backups/Recovery-Kits

D. Immutable Offsite Backup Standard¶

The official offsite platform is Arq 7 on macOS writing to a dedicated private Backblaze B2 bucket through the S3-compatible interface. Object Lock shall be enabled before production data is written, and Arq shall maintain the latest backup record in compliance-mode immutability.

• Arq client-side encryption is mandatory; the encryption password and recovery instructions shall be retained outside JUKEBOX and outside the B2 account.

• Use a bucket-scoped B2 application key with only the permissions Arq requires. Protect the Backblaze account with multi-factor authentication; never use the master application key for the backup client.

• The complete /Volumes/PlexDB/Plex application-data tree is included because it preserves library organization, watch state, artwork, customizations, and operational continuity. The 44 TB media library remains excluded because it is replaceable and economically disproportionate to the recovery benefit.

• Downloads, caches, temporary files, Docker Desktop virtual-machine data, TARDIS Time Machine data, local Restic repositories, and centralized logs are excluded unless a later recovery test proves a specific item is required.

• Application-native exports and the local Restic job run before the Arq offsite job. All three backup layers must complete and pass their verification gate before routine application, container, or macOS upgrades begin.

• The initial cloud seed is a commissioning activity and may span multiple dedicated maintenance windows. Routine upgrades remain deferred until the first complete backup and sample restore are verified.

E. Current Risks and Mitigations¶

Completion Criteria¶

• Backup scope documented.

• Application-native backup locations identified.

• AppData backup job defined and tested.

• At least one service restoration tested from Compose and AppData.

• Disaster-recovery dependencies documented.

• Private B2 bucket created with Object Lock enabled before production upload.

• Arq 7 backup plan configured through the B2 S3-compatible endpoint with immutable records enabled.

• Initial seed, backup verification, and sample restore completed and recorded.

• Monthly sample restores and quarterly full recovery exercises scheduled.

Step 1.6 - Operational Standards¶

A. Server Availability¶

JUKEBOX is a dedicated service host. Its power and sleep behavior shall support continuous availability of containerized services.

B. Container Lifecycle¶

• Containers may be stopped, removed, and recreated as part of normal maintenance.

• Persistent data must survive container replacement.

• Containers shall not be customized through undocumented interactive changes inside the running container.

• Configuration changes shall be made through Compose files, environment files, bind-mounted configuration, or documented application settings.

C. Restart Behavior¶

Services intended to operate continuously shall use an appropriate restart policy. The selected policy must not create uncontrolled restart loops for failed or intentionally stopped services.

D. Controlled Changes¶

Infrastructure changes shall follow documentation-first change control. Before deployment, the governing standard and implementation guide shall record the current state, intended change, rollback path, and a Pending status. Infrastructure may change only after those records are saved. After deployment, the operator shall verify the result and update the implementation guide from Pending to Implemented, recording the outcome and any deviation. Manual Docker Desktop changes that cannot be reproduced from the platform files should be avoided.

E. Maintenance and Cleanup¶

Routine platform maintenance may include removal of unused images, build cache, stopped containers, and obsolete networks. Cleanup shall be performed deliberately and shall not remove named data or active platform dependencies without verification.

F. Shutdown and Restart¶

Planned host shutdowns should stop active workloads cleanly and verify that storage volumes remain available after restart. Following maintenance, the operator shall confirm service health rather than assuming automatic startup succeeded.

Completion Criteria¶

• macOS sleep disabled.

• Docker Desktop configured to start with the host user session.

• Restart policies assigned to persistent services.

• Reboot test completed with required volumes mounted and services restored.

• Operational cleanup procedure documented.

• Documentation-first change procedure documented and followed for infrastructure changes.

Step 1.7 - Platform Design Principles¶

The following principles explain the reasoning behind the technical requirements in this standard. When a future decision is not explicitly covered, the solution most consistent with these principles should be preferred.

Phase 1 Completion Gate¶

• All Step 1.1 through Step 1.6 completion criteria satisfied.

• Platform directory and storage model implemented.

• Test service survives removal, recreation, and host reboot.

• Backup and restoration test completed.

• Phase 1 design principles approved as governing guidance.

Appendix A - Definitions¶

END OF PHASE 1 DRAFT

Document Control¶