# samba-webui

**Repository Path**: llzroot/samba-webui

## Basic Information

- **Project Name**: samba-webui
- **Description**: No description available
- **Primary Language**: HTML
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-30
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Samba WebUI

Lightweight Samba management WebUI for a single Linux host. It runs Samba and the WebUI in one Docker Compose service, then lets an administrator manage SMB shares, Samba users, files, and Samba recycle-bin contents from a browser.

## Safety Notice

This WebUI controls Samba configuration, Samba users, shared files, and recycle-bin deletion. Expose it only on a trusted LAN, VPN, or behind a carefully configured reverse proxy. Do not publish the WebUI directly to the public internet.

## Quick Start

```bash
cp .env.example .env
docker compose up -d --build
```

Open:

```text
http://localhost:8080
```

Edit `.env` before first deployment:

```env
WEBUI_ADMIN_USER=admin
WEBUI_ADMIN_PASSWORD=change-this-password
WEBUI_SECRET_KEY=change-this-random-secret
TZ=Asia/Shanghai
HOST_APP_DATA_DIR=/home/samba-webui/data/app
HOST_SHARES_DIR=/home/samba-webui/data/shares
```

## Ports

- `8080`: WebUI
- `139`: SMB NetBIOS session service
- `445`: SMB over TCP

## Volumes

- `${HOST_APP_DATA_DIR:-./data/app}:/data/app`: SQLite database and application state
- `${HOST_SHARES_DIR:-./data/shares}:/data/shares`: all managed shared folders and files
- `samba-state:/var/lib/samba`: Samba password database and state

All WebUI file operations are restricted to `/data/shares` inside the container.

## Features

- Admin login with signed session cookie.
- Create, edit, list, and delete SMB shares.
- Share-level allowed-user list and read-only/read-write mode.
- Create Samba users, change passwords, list users, and delete users.
- Enable Samba recycle bin per share.
- Browse, upload, rename, download, and delete files.
- Browse recycle-bin files, restore files, delete individual entries, and empty a share's recycle bin.

## Recycle Bin

When enabled for a share, Samba uses:

```text
.recycle/%U
```

inside that share. The WebUI blocks normal file operations on `.recycle`; recycle files are managed from the Recycle Bin tab.

## Share Deletion

Deleting a share is allowed only when its directory is empty. An empty share deletion removes SMB exposure, generated Samba configuration, and the empty directory under `./data/shares/<share-name>`. If the directory contains files or folders, deletion is blocked so the files do not lose their WebUI/SMB entry point.

## Development

Install dependencies:

```bash
python -m pip install -e .[test]
```

Install frontend dependencies:

```bash
cd frontend
npm install
```

Run tests:

```bash
pytest -v
```

Run frontend tests and build:

```bash
cd frontend
npm test
npm run build
```

Start the frontend development server:

```bash
cd frontend
npm run dev
```

Run locally without Samba:

```bash
uvicorn app.main:app --reload --port 8080
```

Local development can test the WebUI and API behavior, but real Samba user and SMB serving behavior requires the Docker image on Linux with Samba installed. The Docker image builds the React frontend first and then copies the compiled static assets into the Python/Samba runtime image.