CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Docker image for running Samba file server, forked from dperson/samba. It provides an Alpine-based container with current Samba versions and built-in macOS compatibility (including optional Time Machine support).

Build and Run Commands

# Build the Docker image
docker build -t samba .

# Run with default configuration
docker run -it -p 139:139 -p 445:445 -d samba -p

# Run with docker-compose (uses example configuration)
docker-compose up -d

# Test the running container
smbclient -L \\localhost -U % -m SMB3

Architecture

Key Files

Dockerfile: Alpine-based image that installs samba and configures /etc/samba/smb.conf with sensible defaults (SMB2/3 only, Time Machine support, recycle bin)
samba.sh: Entrypoint script that handles all configuration via CLI flags and environment variables

Configuration Flow

Container starts with samba.sh as entrypoint (via tini)
Environment variables (SHARE, USER, GLOBAL, etc.) are processed first
CLI flags (-s, -u, -g, etc.) override/add to configuration
Configuration is written to /etc/samba/smb.conf
smbd starts in foreground mode

Configuration Options

Configuration can be done via CLI flags or environment variables:

-s / SHARE: Add shares (format: name;/path;browse;readonly;guest;users;admins;writelist;comment)
-u / USER: Add users (format: username;password;ID;group;GID)
-g / GLOBAL: Set global smb.conf options
-G / GENERIC: Set section-specific smb.conf options
-n / NMBD: Enable NetBIOS daemon (requires ports 137-138/udp)
-p / PERMISSIONS: Fix ownership/permissions on shares
-t / TIMEMACHINE: Enable Time Machine support (basic macOS compatibility is always enabled)

Multiple shares/users: use numbered env vars (SHARE, SHARE2, SHARE3, etc.)

macOS Compatibility

Basic macOS compatibility is enabled by default and includes:

Extended attributes support (icons, labels, metadata)
Proper handling of macOS-specific file operations
Character mapping for special characters
Automatic cleanup of system files (.DS_Store, .apdisk, etc.)

Time Machine support is optional (use -t flag or TIMEMACHINE=1) and adds:

Server advertisement as Time Capsule
Time Machine-specific optimizations
Automatic backup discovery in macOS

Exposed Ports

137/udp, 138/udp: NetBIOS (only needed with -n flag)
139/tcp: SMB over NetBIOS
445/tcp: SMB direct

Default User

Samba runs as smbuser:smb by default. Override with USERID and GROUPID environment variables.

2.7 KiB Raw Blame History