Three-Tier Design

Relevant source files

• Dockerfile
• README.md

Purpose and Scope

This page documents the fundamental three-tier architecture that enables sshfs-mac-docker to provide SSHFS functionality on macOS without requiring macFUSE or kernel extensions. The design isolates complex filesystem operations within a Docker container while exposing results through standard network protocols.

For details on how SSH and SMB protocols are bridged within the container, see Protocol Translation. For network configuration and port mapping specifics, see Network Architecture.

Architectural Overview

The system implements a three-tier design where each tier has distinct responsibilities and runs in different execution environments:

This separation is the core innovation that eliminates the need for macFUSE installation on macOS. All FUSE operations are contained within the Docker container's Linux environment, where FUSE is a native, well-supported technology.

Sources: README.md:1-5

The Three-Tier Structure

Diagram: Three-Tier Architecture with Code Entity Mapping

This diagram maps the architectural tiers to specific code artifacts, showing how the Dockerfile constructs each component.

Sources: README.md:1-90 Dockerfile:1-34

Tier 1: macOS Host Layer

The macOS host layer is intentionally minimal and avoids any kernel-level modifications. This tier's responsibilities are limited to:

Responsibilities

1. Container Lifecycle Management : Building and running the Docker container via docker build and docker run commands
2. User Interaction : Providing the terminal interface for executing commands within the container via docker exec
3. File Access : Mounting the SMB share through macOS Finder's native SMB client

What Does NOT Run Here

Critically, this tier does not include:

• FUSE kernel extensions (no macFUSE required)
• SSHFS client software
• Any SSH connection handling to remote servers
• Filesystem mounting operations

By excluding these components from the macOS host, the system avoids the primary pain point that sshfs-mac-docker was designed to solve: the requirement to install macFUSE and accept kernel extension modifications.

Sources: README.md:1-3

Tier 2: Docker Container Layer

The container layer is the system's core, acting as a protocol bridge and isolation boundary. This tier contains all complex filesystem operations within a controlled Linux environment.

Container Build-Time Setup

The Dockerfile:1-34 constructs this tier through several distinct phases:

Runtime Components

Diagram: Container Internal Structure Mapping to Dockerfile

This diagram shows how runtime components correspond to build-time Dockerfile instructions.

Directory Integration

The symbolic link created at Dockerfile30 is the critical integration point:

This creates /samba-share/remote as a symbolic link pointing to /remote, where SSHFS will mount the remote filesystem. The Samba server serves /samba-share Dockerfile21 making the SSHFS-mounted content accessible via SMB without data duplication.

Sources: Dockerfile:1-34

Tier 3: Remote Infrastructure Layer

The remote infrastructure tier is external to the Docker environment and consists of:

1. Remote SSH Server : The target system that the user specifies as user@host:path in the sshfs command README.md49
2. Remote Filesystem : The actual files and directories being accessed
3. SSH Authentication : Standard SSH protocol authentication (password or key-based)

This tier is completely unaware that access is being proxied through a Docker container and SMB protocol. From the remote server's perspective, it's handling a standard SSHFS connection.

Sources: README.md:36-53

Isolation Strategy and Kernel Extension Avoidance

The macFUSE Problem

On macOS, SSHFS traditionally requires macFUSE (formerly OSXFUSE), which necessitates:

1. Installing a kernel extension (kext)
2. Allowing system extensions in Security & Privacy settings
3. Potential compatibility issues with macOS updates
4. Security concerns about third-party kernel code

Sources: README.md3

The Container Solution

The three-tier design solves this by:

Diagram: Comparison of Approaches - Traditional vs Container-Based

Why This Works

The Docker container provides a Linux environment where FUSE is natively supported Dockerfile:5-6 The container's --privileged flag README.md31 allows FUSE operations within the container without affecting the host macOS kernel.

Sources: README.md:1-31 Dockerfile:5-6

Component Distribution Across Tiers

The following table maps specific components and files to their respective tiers:

Sources: Dockerfile:1-34 README.md:49-60

Data Flow Across Tiers

The three tiers collaborate to enable seamless file access:

Diagram: Cross-Tier Data Flow for File Operations

Each tier maintains clear boundaries:

• Tier 1 handles only SMB protocol communication
• Tier 2 translates between SMB and SSH/FUSE protocols
• Tier 3 provides the actual file data via SSH

Sources: README.md:46-69

Summary

The three-tier design achieves its primary goal of avoiding macFUSE by:

1. Isolating FUSE operations within a Docker container (Tier 2) where Linux provides native FUSE support
2. Exposing the remote filesystem through SMB, which macOS (Tier 1) natively supports
3. Delegating actual file storage and SSH operations to the remote server (Tier 3)

This architecture requires no modifications to the macOS host system, making it a non-invasive solution for accessing remote filesystems via SSHFS on macOS.

Sources: README.md:1-90 Dockerfile:1-34