Getting Started

Relevant source files

• Dockerfile
• README.md

Purpose and Scope

This page provides a high-level overview of the setup and operational workflow for sshfs-mac-docker. It covers the complete lifecycle from building the Docker image to actively accessing remote files through macOS Finder. The material focuses on the sequence of steps required to establish a working system and the key files and commands involved.

For detailed information about specific topics:

Sources: README.md

Setup Overview

The sshfs-mac-docker setup process consists of four distinct phases that must be executed in sequence. Each phase depends on the successful completion of the previous phase.

graph TB
    Phase1["Phase 1: Image Build\ndocker build -t docker-sshfs ."]
Phase2["Phase 2: Container Start\ndocker run --privileged"]
Phase3["Phase 3: Remote Mount\nsshfs user@host:path /samba-share"]
Phase4["Phase 4: macOS Connection\nsmb://container-ip"]
Phase1 --> Phase2
 
   Phase2 --> Phase3
 
   Phase3 --> Phase4
    
 
   Phase1 -.-> Files1["Creates:\n- /remote\n- /samba-share\n- /samba-share/remote (symlink)\n- sshuser account"]
Phase2 -.-> Process2["Starts:\n- smbd daemon\n- Ports 139/445 forwarded"]
Phase3 -.-> Mount3["Mounts:\n- Remote filesystem at /remote\n- Accessible via /samba-share/remote"]
Phase4 -.-> Access4["Enables:\n- Finder access\n- Read/write operations"]

Setup Phase Diagram

Sources: README.md:19-69, Dockerfile:1-34

Key Files and Commands

The following table maps the major system components to their corresponding files and commands:

Sources: README.md:19-86, Dockerfile:1-34

Container Filesystem Layout

The Docker container establishes a specific filesystem structure that enables the SSH-to-SMB protocol bridge. Understanding this layout is essential for troubleshooting and configuration.

Sources: Dockerfile:12, Dockerfile:15, Dockerfile:18, Dockerfile:21, Dockerfile:24, Dockerfile:30

graph TB
    subgraph Container["Container Filesystem"]
subgraph ETC["/etc"]
SmbConf["/etc/samba/smb.conf\n(copied from host)"]
FuseConf["/etc/fuse.conf\n(user_allow_other added)"]
end
        
        subgraph Root["/"]
Remote["/remote\n(SSHFS mount point)\nmkdir at build time"]
SambaShare["/samba-share\n(Samba root directory)\nchmod 777"]
end
        
        subgraph SambaShareContents["/samba-share contents"]
Symlink["/samba-share/remote\n(symbolic link)\nln -s /remote"]
end
        
        subgraph Users["/home"]
SshUserHome["/home/sshuser\n(created by useradd)"]
end
    end
    
 
   Remote -.->|target of symlink| Symlink
 
   SambaShare -->|contains| Symlink
    
    BuildStep1["Dockerfile:12\nRUN mkdir /remote"]
BuildStep2["Dockerfile:15\nRUN mkdir /samba-share"]
BuildStep3["Dockerfile:18\nCOPY smb.conf"]
BuildStep4["Dockerfile:21\nRUN chmod -R 777"]
BuildStep5["Dockerfile:24\nRUN echo user_allow_other"]
BuildStep6["Dockerfile:30\nRUN ln -s /remote"]
BuildStep1 -.-> Remote
 
   BuildStep2 -.-> SambaShare
 
   BuildStep3 -.-> SmbConf
 
   BuildStep4 -.-> SambaShare
 
   BuildStep5 -.-> FuseConf
 
   BuildStep6 -.-> Symlink

Command Sequence

The following diagram shows the exact command sequence required to establish a working system, with the specific flags and options required for each command.

Sources: README.md:22, README.md:31, README.md:41-49, README.md:57-69, Dockerfile:33

sequenceDiagram
    participant User
    participant DockerCLI as "docker CLI"
    participant Container as "docker-sshfs container"
    participant Finder as "macOS Finder"
    
    rect rgb(240, 240, 240)
        Note over User,Container: Build Phase
        User->>DockerCLI: docker build -t docker-sshfs .
        DockerCLI->>DockerCLI: Process Dockerfile:1-34
        DockerCLI->>DockerCLI: Create image with sshfs, samba, sshuser
        DockerCLI-->>User: Image "docker-sshfs" created
    end
    
    rect rgb(240, 240, 240)
        Note over User,Container: Container Start Phase
        User->>DockerCLI: docker run --privileged --name docker-sshfs\n-p 127.0.0.1:139:139 -p 127.0.0.1:445:445 docker-sshfs
        DockerCLI->>Container: Start container
        Container->>Container: Execute CMD: smbd --foreground --no-process-group
        Container-->>DockerCLI: smbd listening on ports 139/445
        Note over Container: Container running, awaiting SSHFS mount
    end
    
    rect rgb(240, 240, 240)
        Note over User,Container: Mount Phase
        User->>DockerCLI: docker exec -it docker-sshfs bash
        DockerCLI->>Container: Attach interactive shell
        User->>Container: sshfs -o allow_other,uid=1000,gid=1000\nuser@host:path /samba-share
        Container->>Container: Mount remote filesystem at /remote\nAccessible via /samba-share/remote symlink
        Container-->>User: Remote filesystem mounted
    end
    
    rect rgb(240, 240, 240)
        Note over User,Finder: Connection Phase
        User->>DockerCLI: docker inspect --format '{{ .NetworkSettings.IPAddress }}'\ndocker-sshfs
        DockerCLI-->>User: Return container IP (e.g., 172.17.0.2)
        User->>Finder: Go → Connect to Server\nsmb://[container-ip]
        Finder->>Container: SMB connection request (ports 139/445)
        Container-->>Finder: Request authentication
        User->>Finder: Connect as Guest
        Finder->>Container: Access /samba-share
        Container-->>Finder: Serve files via smbd
        Note over Finder: Remote files accessible in Finder
    end

stateDiagram-v2
    [*] --> ImageNotBuilt : Repository Cloned
    
    ImageNotBuilt --> ImageBuilt : docker build -t docker-sshfs . Creates - sshuser, /remote, /samba-share, symlink
    
    ImageBuilt --> ContainerRunning : docker run --privileged -p 139 - 139 -p 445 - 445 Starts - smbd daemon (Dockerfile - 33)
    
    ContainerRunning --> RemoteMounted : docker exec + sshfs -o allow_other,uid=1000,gid=1000 Mounts - remote filesystem at /remote
    
    RemoteMounted --> MacConnected : Finder → smb - //[container-ip] Connect as Guest
    
    MacConnected --> FullyOperational : Files accessible in Finder
    
    FullyOperational --> MacConnected : Unmount from Finder
    MacConnected --> RemoteMounted : fusermount -u /samba-share
    RemoteMounted --> ContainerRunning : fusermount -u completes
    ContainerRunning --> ImageBuilt : docker stop docker-sshfs
    
    note right of ImageNotBuilt
        Prerequisites:
        - Docker/OrbStack installed
        - Cloned repository
    end note
    
    note right of RemoteMounted
        Critical mount options:
        - allow_other (Dockerfile : 24)
        - uid=1000,gid=1000 (sshuser uid)
    end note
    
    note right of MacConnected
        Common issue:
        Device or resource busy
        Must unmount from Finder first
    end note

System State Transitions

The system progresses through several distinct states during setup and operation. Each state has specific prerequisites and produces specific outcomes.

Sources: README.md:22-86, Dockerfile:9, Dockerfile:24, Dockerfile:33

Critical Configuration Points

Several configuration elements established during the build process are essential for the system to function correctly:

User Configuration

The sshuser account is created with uid=1000 and gid=1000 Dockerfile9 This uid/gid pairing is referenced in the SSHFS mount command README.md49 to ensure write permissions.

Directory Permissions

The /samba-share directory is set to 777 permissions Dockerfile21 to allow the Samba service to write files, which are then forwarded through the symbolic link to the SSHFS mount.

FUSE Configuration

The user_allow_other option is appended to /etc/fuse.conf Dockerfile24 to enable the allow_other mount option, which permits processes other than the mounting user (including the smbd daemon) to access the mounted filesystem.

Symbolic Link Integration

The symbolic link from /samba-share/remote to /remote Dockerfile30 creates the integration point between the Samba share and the SSHFS mount, allowing Samba to serve files from the remote filesystem without data duplication.

Port Forwarding

Ports 139 and 445 are forwarded to 127.0.0.1 README.md31 to provide localhost-only access to the Samba service, preventing external network exposure while still allowing macOS Finder to connect via the container's internal IP address.

Sources: Dockerfile:9, Dockerfile:21, Dockerfile:24, Dockerfile:30, README.md:31, README.md:49

Quick Reference Command Summary

Sources: README.md:22-86

Next Steps

After completing the basic setup outlined on this page:

1. Review Prerequisites and Platform Requirements for detailed platform considerations, especially regarding OrbStack versus Docker Desktop
2. Follow the detailed steps in Building the Container through Connecting from macOS
3. Consult Unmounting and Cleanup when you need to disconnect or reconfigure
4. If you encounter issues, see Troubleshooting for common problems and solutions
5. For a deeper understanding of the system architecture, see Architecture

Sources: README.md