Building the Container

Relevant source files

• Dockerfile
• README.md

This page documents the process of building the docker-sshfs container image from the Dockerfile. It covers the build command, the components installed during the build, and the filesystem structure created in the resulting image.

For information about running the built container, see Running the Container. For details about individual configuration files, see Configuration Reference.

Build Command

The container image is built using a single Docker command:

This command reads the Dockerfile:1-34 in the repository root and creates a Docker image tagged as docker-sshfs. The build process installs all necessary packages, creates the required directory structure, and configures both SSHFS and Samba services.

Sources: README.md:19-23

Dockerfile Structure

The build process follows a sequential set of instructions that construct the container image from a base Ubuntu system to a fully configured SSHFS/Samba server.

flowchart TD
 
   Start["FROM ubuntu:latest"] --> Update["apt-get update"]
Update --> Install["apt-get install -y sshfs samba"]
Install --> CreateUser["useradd -m sshuser\necho 'sshuser:sshpass' / chpasswd"]
CreateUser --> MkdirRemote["mkdir /remote"]
MkdirRemote --> MkdirSamba["mkdir /samba-share"]
MkdirSamba --> CopyConf["COPY smb.conf /etc/samba/smb.conf"]
CopyConf --> ChmodSamba["chmod -R 777 /samba-share"]
ChmodSamba --> FuseConf["echo 'user_allow_other' >> /etc/fuse.conf"]
FuseConf --> Expose["EXPOSE 139 445"]
Expose --> Symlink["ln -s /remote /samba-share/remote"]
Symlink --> CMD["CMD smbd --foreground --no-process-group --debug-stdout"]
CMD --> End["Image Ready"]

Build Process Flow

Sources: Dockerfile:1-34

Base Image and Package Installation

The build starts from ubuntu:latest and installs two critical packages:

These installations occur at Dockerfile:2-6:

FROM ubuntu:latest
RUN apt-get update && \
    apt-get install -y sshfs samba

The sshfs package provides the FUSE-based SSH filesystem mounting capability, while samba provides the smbd daemon and SMB protocol implementation that macOS can connect to.

Sources: Dockerfile:2-6

User Account Creation

A non-root user account is created for running SSHFS operations:

useradd -m sshuser && echo "sshuser:sshpass" | chpasswd

This command at Dockerfile9 creates:

• Username: sshuser
• Password: sshpass
• Home directory: /home/sshuser (created with -m flag)

The sshuser account is referenced in the Samba configuration via the force user = sshuser directive, ensuring all file operations through Samba appear to originate from this user.

Sources: Dockerfile:8-9

Directory Structure Creation

The build creates two primary mount point directories:

Directory Purposes

The /samba-share directory receives chmod -R 777 permissions at Dockerfile21 to ensure the Samba service can write to it regardless of the user context.

Sources: Dockerfile:11-15 Dockerfile:20-21 Dockerfile:29-30

Configuration File Integration

The build copies the Samba configuration file into the container:

COPY smb.conf /etc/samba/smb.conf

This instruction at Dockerfile18 copies the smb.conf:1-19 file from the build context into the container's standard Samba configuration location. The configuration defines the SMB share parameters including guest access, user forcing, and protocol versions. For details about the configuration contents, see Samba Configuration (smb.conf)).

Sources: Dockerfile:17-18

FUSE Configuration

The build modifies the FUSE configuration to enable cross-user filesystem access:

echo "user_allow_other" >> /etc/fuse.conf

This line at Dockerfile24 appends the user_allow_other option to /etc/fuse.conf. This setting is critical because:

• SSHFS mounts are performed by the sshuser account
• The Samba daemon (smbd) runs as a different user
• Without user_allow_other, smbd cannot access SSHFS-mounted filesystems

For more details on this configuration, see FUSE Configuration.

Sources: Dockerfile:23-24

Network Port Exposure

The Dockerfile exposes two ports for Samba connectivity:

EXPOSE 139 445

At Dockerfile27 the build declares:

• Port 139 : NetBIOS Session Service (legacy SMB)
• Port 445 : SMB over TCP/IP (modern SMB)

These ports are later mapped to the host system when running the container. See Running the Container for details on port mapping configuration.

Sources: Dockerfile:26-27

Symbolic Link Creation

A critical integration point is established by creating a symbolic link:

ln -s /remote /samba-share/remote

This command at Dockerfile30 creates the symbolic link /samba-share/remote that points to /remote. This link serves as the bridge between the SSHFS mount point and the Samba share:

flowchart LR
 
   SSHFS["SSHFS Mount\n(future operation)"] --> Remote["/remote"]
Remote -.->|referenced by| Symlink["/samba-share/remote\n(symbolic link)"]
Symlink --> SambaDir["/samba-share"]
SambaDir --> Samba["smbd service\n(exposes directory)"]
Samba --> Mac["macOS Finder\n(SMB client)"]

When a remote filesystem is mounted to /remote at runtime, it automatically becomes accessible as /samba-share/remote through the symbolic link, allowing Samba to serve the remote files without data duplication.

Sources: Dockerfile:29-30

Container Entry Point

The final build instruction specifies the container's main process:

CMD ["smbd", "--foreground", "--no-process-group", "--debug-stdout"]

At Dockerfile33 this command configures the container to:

• Execute smbd (Samba daemon) as the primary process
• Run in --foreground mode (does not daemonize)
• Use --no-process-group to avoid creating a process group
• Enable --debug-stdout to send logs to stdout for Docker visibility

When the container starts, this command runs automatically, launching the Samba server and keeping the container alive. The container remains running as long as the smbd process is active.

Sources: Dockerfile:32-34

Build Output Summary

The completed image contains the following components:

The resulting image is self-contained and ready to run. No additional configuration is required at container startup, though SSHFS mounting must be performed manually after the container is running. See Mounting Remote Filesystems for runtime mount procedures.

Sources: Dockerfile:1-34 README.md:19-23

Build Verification

After running docker build -t docker-sshfs ., you can verify the image was created successfully:

The output should display the docker-sshfs image with a recent creation timestamp. The image size typically ranges from 300-400 MB depending on the base Ubuntu image version and installed package versions.

To proceed with using the container, continue to Running the Container.

Sources: README.md:19-23