9

Quick Start with weed mini

Chris Lu edited this page 2026-01-29 22:49:54 -08:00

Table of Contents

• Quick Start with weed mini
• Overview
• Features
• Quick Start
• Basic Usage
• Custom Data Directory
• Custom Port
• S3 Credentials Setup
• Option 1: Environment Variables (Recommended)
• Option 2: Admin UI
• Default S3 Access
• Enabling Authentication
• Using S3 Endpoint
• Unauthenticated Access (Default)
• Authenticated Access
• Web Interfaces
• Admin UI
• Filer UI
• Master UI
• Common Options
• Stopping the Server
• Next Steps
• Performance Considerations
• Related Documentation

Quick Start with weed mini

Note

: The weed mini command is designed for learning, development, and testing only. It may not guarantee backward compatibility between versions. For production deployments, use the Multi-Component Setup.

Overview

weed mini is an all-in-one SeaweedFS command designed specifically for S3 beginners, small deployments, and development environments. It starts all essential SeaweedFS components in a single process with optimized defaults. If there are enough disk space, weed mini should be trouble-free in most cases.

Perfect for:

• Learning SeaweedFS and S3-compatible storage
• Development and testing
• Prototyping
• Small deployments with minimal configuration

Features

The weed mini command starts:

• Master Server - Cluster coordination
• Volume Server - Data storage
• Filer - Hierarchical file system interface
• S3 Gateway - S3-compatible API endpoint
• WebDAV Gateway - WebDAV file access
• Admin UI - Web-based management console
• Maintenance Worker - Background tasks (vacuuming, erasure coding, balancing)

All components run in a single process with optimized settings:

• Auto-configured volume size limit (suitable for most use cases)
• Auto-scaling volumes based on available disk space
• Single master mode (no cluster coordination overhead)
• 1-second pre-stop time (faster startup/shutdown)
• Embedded IAM for S3 credential management

Quick Start

Basic Usage

weed mini -dir=/data

This starts all services with the default configuration:

• Master UI: http://localhost:9333
• Filer UI: http://localhost:8888
• S3 Endpoint: http://localhost:8333
• WebDAV: http://localhost:7333
• Admin UI: http://localhost:23646
• Volume Server: http://localhost:9340

Custom Data Directory

weed mini -dir=/path/to/data

Custom Port

weed mini -dir=/data -master.port=9444 -s3.port=8334

S3 Credentials Setup

Option 1: Environment Variables (Recommended)

Set AWS credentials before starting:

export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export S3_ENDPOINT=http://localhost:8333
weed mini -dir=/data

The initial IAM config will be created automatically for the mini user with these credentials.

Option 2: Admin UI

1. Start weed mini
2. Open http://localhost:23646 in your browser
3. Navigate to the IAM/Credentials section
4. Create new identities with S3 credentials

Default S3 Access

By default, the SeaweedFS S3 gateway starts in "Allow All" mode if no S3 credentials are configured. This is designed for maximum ease of use in development and testing environments, and it applies to all S3 instances, including weed mini.

• No credentials configured: All S3 operations are allowed without authentication.
• Credentials added: As soon as any credentials are configured (either initially via flags/env vars or dynamically via the Admin UI/Shell), authentication is automatically enabled and all requests will then require valid credentials.

Enabling Authentication

To enable authentication for weed mini, use one of the following methods:

1. Environment Variables: Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY before starting.

export AWS_ACCESS_KEY_ID=any export AWS_SECRET_ACCESS_KEY=any export S3_ENDPOINT=http://localhost:8333 weed mini -dir=/data

2. **Config File**: Use the `-s3.config` flag with a JSON credentials file.
   ```bash
   weed mini -dir=/data -s3.config=s3.config

3. Dynamic Configuration: Start normally, then add users through the Admin UI or weed shell. The server will automatically switch from "Allow All" to "Authentication Required" mode.

---

Using S3 Endpoint

Unauthenticated Access (Default)

If you haven't configured any credentials, you can use the S3 endpoint with the --no-sign-request flag in the AWS CLI:

# Create a bucket
aws --endpoint-url $S3_ENDPOINT s3 mb s3://my-bucket --no-sign-request

# List contents
aws --endpoint-url $S3_ENDPOINT s3 ls s3://my-bucket/ --no-sign-request

Authenticated Access

If you have configured credentials, you'll need to use your access keys:

# Using AWS CLI
aws configure
# AWS Access Key ID: <your-access-key>
# AWS Secret Access Key: <your-secret-key>

# Use the local endpoint
aws --endpoint-url $S3_ENDPOINT s3 ls s3://my-bucket/

Web Interfaces

Admin UI

• URL: http://localhost:23646
• Purpose: User/credential management, task monitoring, system status
• No authentication by default (configurable)

Filer UI

• URL: http://localhost:8888
• Purpose: Hierarchical file system browser
• View and manage files with directory structure

Master UI

• URL: http://localhost:9333
• Purpose: Cluster topology and volume management
• Monitor volume distribution across servers

Common Options

# Specify data directory
weed mini -dir=/data

# Custom S3 port
weed mini -dir=/data -s3.port=8334

# Custom IAM config file
weed mini -dir=/data -s3.iam.config=/path/to/iam.json

Stopping the Server

# Press Ctrl+C in the terminal
# All services will gracefully shut down

Next Steps

• Read S3-API-FAQ.md for S3-specific questions
• Check Filer-Commands-and-Operations.md for file operations
• See Admin-UI.md for admin interface documentation
• Explore Production-Setup.md when ready to scale beyond mini

Performance Considerations

The mini command is optimized for development and small deployments. For production workloads:

• Separate components on different servers (see Production-Setup.md)
• Increase volume size limits based on your needs
• Use dedicated object storage for cloud integration
• Configure replication for data safety
• Set up monitoring and alerting

Related Documentation

• Getting-Started.md - Traditional multi-process setup
• Production-Setup.md - Production deployment guidance
• S3-Credentials.md - Detailed credential management
• Admin-UI.md - Admin interface documentation
• Docker-Compose-for-S3.md - Docker deployment

Introduction

• Quick Start with weed mini
• Components
• Getting Started
• Production Setup
• Benchmarks
• FAQ
• Applications

API

• Master Server API
• Volume Server API
• Filer Server API
• Client Libraries
• SeaweedFS Java Client

Configuration

• Replication
• Store file with a Time To Live
• Failover Master Server
• Erasure coding for warm storage
• Server Startup via Systemd
• Environment Variables

Filer

• Filer Setup
• Directories and Files
• File Operations Quick Reference
• Data Structure for Large Files
• Filer Data Encryption
• Filer Commands and Operations
• Filer JWT Use
• TUS Resumable Uploads

Filer Stores

• Filer Cassandra Setup
• Filer Redis Setup
• Super Large Directories
• Path-Specific Filer Store
• Choosing a Filer Store
• Customize Filer Store

Management

• Admin UI
• Worker

Advanced Filer Configurations

• Migrate to Filer Store
• Add New Filer Store
• Filer Store Replication
• Filer Active Active cross cluster continuous synchronization
• Filer as a Key-Large-Value Store
• Path Specific Configuration
• Filer Change Data Capture

FUSE Mount

• FIO benchmark
• fstab

WebDAV

Cloud Drive

• Cloud Drive Benefits
• Cloud Drive Architecture
• Configure Remote Storage
• Mount Remote Storage
• Cache Remote Storage
• Cloud Drive Quick Setup
• Gateway to Remote Object Storage

AWS S3 API

• Amazon S3 API
• S3 Conditional Operations
• S3 CORS
• S3 Object Lock and Retention
• S3 Object Versioning
• S3 API Benchmark
• S3 API FAQ
• S3 Bucket Quota
• S3 Rate Limiting
• S3 API Audit log
• S3 Nginx Proxy
• Docker Compose for S3

S3 Table Bucket

• S3 Table Bucket

S3 Authentication & IAM

• S3 Configuration - Start Here
• S3 Credentials (-s3.config)
• OIDC Integration (-s3.iam.config)
• S3 Policy Variables
• Amazon IAM API
• AWS IAM CLI

Server-Side Encryption

• Server-Side Encryption
• Server-Side Encryption SSE-KMS
• Server-Side Encryption SSE-C

S3 Client Tools

• AWS CLI with SeaweedFS
• s3cmd with SeaweedFS
• rclone with SeaweedFS
• restic with SeaweedFS
• nodejs with Seaweed S3

Machine Learning

• TensorFlow with SeaweedFS

HDFS

• Hadoop Compatible File System
• run Spark on SeaweedFS
• run HBase on SeaweedFS
• run Presto on SeaweedFS
• Hadoop Benchmark
• HDFS via S3 connector

Replication and Backup

• Async Replication to another Filer [Deprecated]
• Async Backup
• Async Filer Metadata Backup
• Async Replication to Cloud [Deprecated]
• Kubernetes Backups and Recovery with K8up

Metadata Change Events

• Filer Metadata Events
• Filer Notification Webhook

Messaging

• Structured Data Lake with SMQ and SQL
• Seaweed Message Queue
• SQL Queries on Message Queue
• SQL Quick Reference
• PostgreSQL-compatible Server weed db
• Pub-Sub to SMQ to SQL
• Kafka to Kafka Gateway to SMQ to SQL

Use Cases

• Use Cases
• Actual Users

Operations

• System Metrics
• weed shell
• Data Backup
• Deployment to Kubernetes and Minikube

Advanced

• Large File Handling
• Optimization
• Volume Management
• Tiered Storage
• Cloud Tier
• Cloud Monitoring
• Load Command Line Options from a file
• SRV Service Discovery
• Volume Files Structure

Security

• Security Overview
• Security Configuration
• Cryptography and FIPS Compliance
• Run Blob Storage on Public Internet

Misc Use Case Examples

• UrBackup with SeaweedFS
• Docker Image Registry with SeaweedFS
• SeaweedFS in Docker Swarm
• Words from SeaweedFS Users
• Independent Benchmarks
• Hardware