fernandodelucca/smb-mgmt repository overview

⁠smb-mgmt

Modern web management console for Samba file servers — Samba and its management UI in one container. Built with Go and Angular, published multi-arch for amd64 and arm64.

The image ships Samba 4.24.x (Debian trixie) together with the smb-mgmt console, which supervises smbd/nmbd/winbind itself: the services you started come back after a restart, redeploy or --force-recreate, and accounts created through the app are recreated on boot with their original uid/gid.

⁠Quick start

docker run -d --name smb-mgmt \
  -p 8080:8080 -p 139:139 -p 445:445 \
  -v smb-mgmt-data:/var/lib/smb-mgmt \
  -v samba-lib:/var/lib/samba \
  -v samba-etc:/etc/samba \
  -v /path/to/your/shares:/srv/samba \
  --restart unless-stopped \
  fernandodelucca/smb-mgmt:latest

Open http://localhost:8080 — the first visit asks you to create the initial admin account. SMB itself is served from the same container on ports 139/445.

⁠Docker Compose

services:
  smb-mgmt:
    image: fernandodelucca/smb-mgmt:latest
    ports:
      - "8080:8080"
      - "139:139"
      - "445:445"
    environment:
      SMB_MGMT_LOG_DIR: /var/log/smb-mgmt
      # SMB_MGMT_TERMINAL: "1"        # enable the recorded, admin-only web terminal
      # SMB_MGMT_TLS_SELF_SIGNED: "1" # HTTPS with a persisted self-signed cert
    volumes:
      - smb-mgmt-data:/var/lib/smb-mgmt   # app database (accounts, config history, audit)
      - samba-lib:/var/lib/samba          # Samba passdb (SMB password hashes)
      - samba-etc:/etc/samba              # smb.conf (seeded on first boot)
      - ./shares:/srv/samba               # your share data
      - ./logs:/var/log/smb-mgmt          # access.log / error.log (CLF)
      - ./samba-logs:/var/log/samba       # Samba daemon logs (shown in the UI)
    restart: unless-stopped

volumes:
  smb-mgmt-data:
  samba-lib:
  samba-etc:

⁠What you get

• Every smb.conf parameter of Samba 4.24.x in a schema-driven UI — search, one tab per functional group, type-aware validation, defaults, and descriptions translated into English, Portuguese, Spanish and German.
• Safe apply pipeline — changes are drafted and versioned first; every apply validates with testparm, writes smb.conf atomically with a backup, reloads Samba and rolls back automatically on failure. Visual diff before applying, drift detection for out-of-band edits, full history with restore, and drafts can be discarded into history and applied later.
• Shares — create, edit, enable/disable, per-share disk usage, guided creation of the share directory.
• Users & groups — Samba users (passdb) plus UNIX accounts, POSIX groups and memberships, all persisted by the app and restored on boot with exact uid/gid, so SIDs and file ownership survive redeploys.
• File browser — confined to the share roots (path-traversal and symlink-escape safe): text editing with syntax highlighting, image preview, upload/download, POSIX permissions and ACLs from the UI.
• Live view — active SMB sessions and open files, service control, host CPU/memory/network metrics on the dashboard.
• Active Directory — join/leave a domain, winbind status.
• Operations — curated log viewer (Samba daemon logs + the console's own access/error logs), audit trail of every change, Prometheus metrics at /metrics (admin session required), optional recorded web terminal (admin-only, off by default).
• Access control — roles: viewer (read-only), operator (manage Samba), admin (everything). Session cookies, same-origin enforcement, rate-limited login.
• Built-in container HEALTHCHECK; tini as PID 1.

⁠Tags

⁠Ports

⁠Volumes

Persist /var/lib/smb-mgmt and /var/lib/samba together: the first holds the account records the entrypoint restores on boot, the second holds the matching SMB password hashes.

⁠Configuration (environment variables)

⁠Security notes

This is a privileged management console — treat it like one:

• Don't expose port 8080 beyond your management network. Bind a specific interface (SMB_MGMT_LISTEN=10.0.10.5:8443) and use TLS — either terminated by the app (cert/key or self-signed) or by a reverse proxy (then set SMB_MGMT_SECURE_COOKIES=1 and keep the app on loopback).
• The first account created is the admin; add viewer/operator accounts for daily use.
• Every configuration change is audited (who, what, when, from where).

⁠Upgrading

Pull the new tag and recreate the container — state lives in the volumes. Rolling back the image is equally safe: database migrations are additive.

docker pull fernandodelucca/smb-mgmt:latest
docker compose up -d

⁠License

MIT