SambaNAS Rest Administration Tool

SRAT (SambaNAS REST Administration Tool) is a new system designed to provide a simplified user interface for configuring SAMBA. It has been developed to work within Home Assistant, specifically for this addon, but can also be used in other contexts.

Currently under development and in an alpha state, SRAT is set to become the preferred system for configuring and using this addon, eventually "retiring" the YAML configuration.

• Installation
  • Local Development
• Home Assistant Custom Component
  • Install via HACS (recommended)
  • Manual Install
• Usage
  • Feature Documentation
• Database
• Sponsor
• Known Issues
• Enhanced Logging System
  • Key Logging Features
  • Quick Logging Examples
• Documentation Validation
• Security scanning
• Building the Project
• Testing and Coverage
  • Running Tests
• Contribute
• License
• Development: Pre-Commit Hooks

👷 This is a part for new SambaNas2 Home Assistant Addon. 👷

Installation

The installation of this add-on is straightforward and similar to any other Home Assistant add-on.

Add our Home Assistant add-ons repository to your Home Assistant instance:

or

Add our Home Assistant BETA add-ons repository to your Home Assistant instance:

Local Development

For local development setup, follow the instructions below for back-end and frontend development.

Home Assistant Custom Component

SRAT includes a HACS-compatible Home Assistant custom component at custom_components/srat/. It communicates with the SRAT back-end exclusively via WebSocket, supporting Supervisor autodiscovery and a UI configuration wizard.

For full details, see Home Assistant Integration.

Install via HACS (recommended)

1. Open HACS in Home Assistant.
2. Go to Integrations → three-dot menu → Custom repositories.
3. Add https://github.com/dianlight/srat as an Integration.
4. Search for "SRAT" and install it.
5. Restart Home Assistant.

Manual Install

1. Download srat.zip from the latest release.
2. Extract the contents into config/custom_components/srat/.
3. Restart Home Assistant.

Usage

SRAT can be used to manage Samba shares, users, and configurations via a modern web UI or REST API. For detailed feature usage, see the documentation in the docs/ folder or access the API docs at /docs when running the back-end server.

Feature Documentation

• Settings Documentation - Complete reference for all SRAT settings
• SMB over QUIC - Enhanced performance and security with QUIC transport protocol
• Telemetry Configuration - Configure error reporting and monitoring
• Home Assistant Integration - Integration with Home Assistant

Database

SRAT uses SQLite for persistence via the GORM ORM. The back-end initializes the database with resilience-focused defaults:

• journal_mode=WAL for safe readers during writes
• busy_timeout=5000 ms to reduce transient SQLITE_BUSY
• synchronous=NORMAL tuned for WAL
• foreign_keys=ON
• cache=shared
• connection pool limited to 1 open/idle connection (embedded DB best practice)

You can set the database path via the --db flag when running the server or CLI. For example:

• File on disk (recommended for production): --db /data/srat.db
• In-memory for tests/dev: --db "file::memory:?cache=shared&_pragma=foreign_keys(1)"

Sponsor

Known Issues

Enhanced Logging System

SRAT includes a comprehensive logging system with the tlog package. For detailed information about logging capabilities, see TLOG Repository.

Key Logging Features

• Professional Formatting: Powered by samber/slog-formatter with automatic error structuring
• Security-First: Automatic masking of sensitive data (passwords, tokens, API keys, IP addresses)
• Developer-Friendly: Color-coded output with terminal detection and level-based coloring
• Production-Ready: Thread-safe operations with configurable output formats
• Context-Aware: Automatic extraction and display of request/trace/user context

Quick Logging Examples

import "github.com/dianlight/srat/tlog"

// Basic usage with enhanced formatting
tlog.Info("Server started", "port", 8080, "version", "1.0.0")
tlog.Error("Database connection failed", "error", err, "host", "localhost")

// Context-aware logging
ctx := context.WithValue(context.Background(), "request_id", "req-12345")
tlog.InfoContext(ctx, "Processing request", "method", "GET", "path", "/api/users")

// Enable security features
tlog.EnableSensitiveDataHiding(true) // Auto-masks passwords, tokens, IPs
tlog.EnableColors(true)              // Color output (auto-disabled if not terminal)

Documentation Validation

SRAT includes comprehensive documentation validation tools with GitHub Flavored Markdown (GFM) support:

# Check all documentation (GFM-aware)
make docs-validate

# Auto-fix formatting issues
make docs-fix

# Show all documentation commands
make docs-help

The validation includes:

• Markdown linting and formatting (markdownlint with GFM support)
• Link and image checking (Lychee - fast and reliable)
• Spell checking (cspell with project vocabulary)
• Prose linting (Vale for style and consistency)
• Content structure validation

For more details, see Documentation Validation Setup and Documentation Guidelines.

Security scanning

This project uses gosec to scan Go code for common security issues.

Quick usage:

• Run full repo security check: make security
• Or only back-end: cd backend && make gosec

Notes:

• Generated code is excluded with -exclude-generated.
• The Makefile will install gosec automatically if it's missing (via go install).

Building the Project

# Build backend
cd backend && make build

# Build frontend
cd frontend && bun run build

# Check custom component (lint + type-check + tests)
cd custom_components && make check

# Build all architectures
make ALL

Testing and Coverage

SRAT maintains high test coverage across both back-end and frontend. The coverage badges at the top of this README are automatically updated.

📊 View Detailed Coverage Report & History →

Running Tests

# Run backend tests with individual package coverage
cd backend && make test

# Run frontend tests with coverage
cd frontend && bun test --coverage

# Run custom component tests (lint + type-check + pytest)
cd custom_components && make check

# Update coverage badges in README and TEST_COVERAGE.md
bash scripts/update-coverage-badges.sh

Contribute

You can use this section to highlight how people can contribute to your project.

You can add information on how they can open issues or how they can sponsor the project.

License

Apache 2.0 license

Development: Pre-Commit Hooks

This repository manages all git hooks via prek. Don’t add scripts under .git/hooks or set core.hooksPath.

Quick start:

• Install prek (bun install -g prek)
• Install hooks: prek install && prek install --hook-type pre-push
• Run all hooks: prek run --all-files

Enforced hooks:

• On commit: gosec security scan for back-end Go changes (high severity/high confidence)
• On push: back-end quick build + test

See .pre-commit-config.yaml for full list. The legacy .githooks directory is deprecated.