bfren/samba repository overview

⁠Samba

Docker Hub⁠ - Quay.io⁠ - bfren ecosystem⁠

⁠Introduction

Samba⁠ file server, sharing folders with Windows, macOS and Linux over SMB. Users and shares are defined in one JSON file, so there's no smb.conf to write.

It is built on Alpine + S6⁠, with Samba from Alpine's packages.

⁠Quickstart

docker-compose.yml:

services:
  samba:
    image: quay.io/bfren/samba:3.2
    restart: unless-stopped
    ports:
      - "0.0.0.0:445:445"
    environment:
      - BF_SAMBA_UID=1000
    volumes:
      - ./v/shares.json:/files/shares.json:ro
      - ./v/docs:/files/docs
      - ./v/public:/files/public

v/shares.json:

{
    "$schema": "https://schemas.bfren.dev/docker/samba/shares.json",
    "users": [
        { "name": "fred", "pass": "change-me" }
    ],
    "shares": [
        { "name": "docs", "comment": "Documents", "users": [ "fred" ] },
        { "name": "public", "users": [ "*" ] }
    ]
}

Run docker compose up -d, then connect to \\<server>\docs (Windows) or smb://<server>/docs (macOS / Linux) as fred. See shares-conf-sample.json for more.

⁠Features

• 📁 Users and shares defined in one JSON file, with a schema for validation and autocomplete
• 👥 Each share limited to its users, or open to guests
• 👤 Everything is written as one user, so files on the host have the owner you choose
• 🔒 SMB over TCP port 445 only
• 🩺 Health check that lists the shares
• 🧪 Built-in tests

⁠Tags

Images are published to Docker Hub (bfren/samba) and Quay.io (quay.io/bfren/samba) for linux/amd64, linux/arm/v7 and linux/arm64, with Samba 4.23.8 on Alpine 3.24.

⁠Configuration

⁠Ports

⁠Volumes

⁠shares.json

/files/shares.json must exist - the container stops without it.

Public shares are open to everyone who can reach the server, without a password, and are always browseable and writeable.

⁠Environment Variables

See Alpine + S6⁠ for BF_DEBUG, BF_TZ and the other base image variables.

⁠How It Works

On every start:

1. A samba system user is created with BF_SAMBA_UID (if it doesn't exist yet).
2. Each user in shares.json that doesn't exist yet is created, with its Samba password.
3. smb.conf is generated, with a section for each share. Every share uses force user = samba, so whoever connects, files are created and changed as samba.

Then smbd runs under S6, logging to docker logs. The container stops if it crashes. Only smbd runs - there's no NetBIOS name service (nmbd), so the server may not appear when browsing the network: connect to it by name or address.

The health check (every 30 seconds) lists the shares as a guest, using SMB3.

⁠Testing

./test.nu   # builds the image and runs /test
./run.sh    # builds the image and opens a shell, using shares-conf-sample.json

/test runs this image's tests alongside the base images' tests: loading shares.json, generating each share (limited, public, browseable and writeable), the generated smb.conf, and the installed Samba version.

⁠Troubleshooting

⁠The container stops straight after starting

/files/shares.json is missing or isn't valid JSON - check docker logs <container>.

⁠I changed a password but the old one still works

Users are only created once, so changes to pass are ignored until the container is recreated (docker compose up -d --force-recreate). Or change it straight away with docker exec -it <container> smbpasswd <name>.

⁠Files on the host belong to the wrong user

Set BF_SAMBA_UID to the UID of the user who owns the folders on the host (id -u), then recreate the container.

⁠I can't see the server when browsing the network

There is no NetBIOS service - connect directly, e.g. \\192.168.1.10\docs.

⁠FAQs

⁠Can I use the same share for several users with different permissions?

Not within one share - create a separate share for each set of permissions.

⁠Licence

⁠Copyright