From e480b246dcabeec3e021c6c61043fac4063bcea3 Mon Sep 17 00:00:00 2001 From: Chris Lu Date: Sat, 20 Dec 2025 21:21:31 -0800 Subject: [PATCH] Add wiki documentation for weed mini command - Create new 'Quick-Start-with-weed-mini.md' with comprehensive guide - Update Getting-Started.md to recommend weed mini for beginners - Add link to wiki sidebar for easy navigation - Include quick start examples, configuration options, and troubleshooting - Document S3 credentials setup and usage examples - Link to related documentation for further learning --- Getting-Started.md | 22 +++- Quick-Start-with-weed-mini.md | 235 ++++++++++++++++++++++++++++++++++ _Sidebar.md | 1 + 3 files changed, 256 insertions(+), 2 deletions(-) create mode 100644 Quick-Start-with-weed-mini.md diff --git a/Getting-Started.md b/Getting-Started.md index 0ce0cea..e27f35f 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -1,8 +1,26 @@ # Getting Started -## Installing SeaweedFS +## Quick Start with `weed mini` (Recommended for Beginners) -Download the latest official release from https://github.com/seaweedfs/seaweedfs/releases. +The easiest way to get started with SeaweedFS is using the `weed mini` command, which starts all components in one process with sensible defaults: + +```bash +weed mini -dir=/data +``` + +This gives you a complete SeaweedFS setup including S3 compatibility, all accessible via simple web interfaces. See [Quick-Start-with-weed-mini.md](Quick-Start-with-weed-mini.md) for detailed instructions. + +**Perfect for:** +- Learning SeaweedFS +- Development and testing +- S3 beginners +- Prototyping + +--- + +## Traditional Setup (For Advanced Users) + +For production deployments or if you prefer separating components, follow the manual setup instructions below. Decompress the downloaded file. You will only find one executable file, either "weed" on most systems or "weed.exe" on windows. diff --git a/Quick-Start-with-weed-mini.md b/Quick-Start-with-weed-mini.md new file mode 100644 index 0000000..e256110 --- /dev/null +++ b/Quick-Start-with-weed-mini.md @@ -0,0 +1,235 @@ +# Quick Start with `weed mini` + +## 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. + +**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: +- 128MB 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 + +```bash +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 + +```bash +weed mini -dir=/path/to/data +``` + +### Custom Port + +```bash +weed mini -dir=/data -master.port=9444 -s3.port=8334 +``` + +## S3 Credentials Setup + +### Option 1: Environment Variables (Recommended) + +Set AWS credentials before starting: + +```bash +export AWS_ACCESS_KEY_ID=your-access-key +export AWS_SECRET_ACCESS_KEY=your-secret-key +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 + +## Using S3 Endpoint + +### Configure S3 Client + +```bash +# Using AWS CLI +aws configure +# AWS Access Key ID: +# AWS Secret Access Key: +# Default region: [leave blank] +# Default output format: [leave blank] + +# Use the local endpoint +aws s3 --endpoint-url=http://localhost:8333 ls +``` + +### Create and Use Buckets + +```bash +# Create a bucket +aws s3 --endpoint-url=http://localhost:8333 mb s3://my-bucket + +# Upload a file +aws s3 --endpoint-url=http://localhost:8333 cp myfile.txt s3://my-bucket/ + +# List bucket contents +aws s3 --endpoint-url=http://localhost:8333 ls s3://my-bucket/ + +# Download a file +aws s3 --endpoint-url=http://localhost:8333 cp s3://my-bucket/myfile.txt ./ +``` + +## 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 + +## WebDAV Access + +Mount the WebDAV server on your system: + +### macOS +1. Open Finder +2. Press Cmd+K (or Go → Connect to Server) +3. Enter: `http://localhost:7333/` +4. Files are accessible at `/buckets/` + +### Linux +```bash +sudo apt-get install davfs2 +sudo mount -t davfs http://localhost:7333/ /mnt/webdav +# Files at /mnt/webdav/buckets/ +``` + +### Windows +1. In File Explorer, right-click on "This PC" +2. Select "Map network drive" +3. Enter: `\\localhost:7333` +4. Files are accessible as network drive + +## Common Options + +```bash +# Specify data directory +weed mini -dir=/data + +# Custom master port +weed mini -dir=/data -master.port=9444 + +# Custom S3 port +weed mini -dir=/data -s3.port=8334 + +# Custom volume size limit (in MB) +weed mini -dir=/data -master.volumeSizeLimitMB=256 + +# Disable HTTP (gRPC only) +weed mini -dir=/data -disableHttp + +# Enable debug mode +weed mini -dir=/data -debug + +# Custom IAM config file +weed mini -dir=/data -s3.iam.config=/path/to/iam.json +``` + +## Stopping the Server + +```bash +# Press Ctrl+C in the terminal +# All services will gracefully shut down +``` + +## Troubleshooting + +### Health Check Warnings + +During startup, you may see health check warnings like: +``` +Health check for Master failed (service may still be functional, retries may succeed) +``` + +This is normal during rapid startup. Services will continue initializing and should become functional within a few seconds. + +### Port Already in Use + +If a port is already in use: +```bash +# Use custom ports +weed mini -dir=/data -master.port=9444 -s3.port=8334 -filer.port=8889 +``` + +### File Permission Errors + +Ensure the data directory is writable: +```bash +mkdir -p /data +chmod 755 /data +weed mini -dir=/data +``` + +## Next Steps + +- Read [S3-API-FAQ.md](S3-API-FAQ.md) for S3-specific questions +- Check [Filer-Commands-and-Operations.md](Filer-Commands-and-Operations.md) for file operations +- See [Admin-UI.md](Admin-UI.md) for admin interface documentation +- Explore [Production-Setup.md](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](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](Getting-Started.md) - Traditional multi-process setup +- [Production-Setup.md](Production-Setup.md) - Production deployment guidance +- [S3-Credentials.md](S3-Credentials.md) - Detailed credential management +- [Admin-UI.md](Admin-UI.md) - Admin interface documentation +- [Docker-Compose-for-S3.md](Docker-Compose-for-S3.md) - Docker deployment diff --git a/_Sidebar.md b/_Sidebar.md index 3aa5843..4ce14a9 100644 --- a/_Sidebar.md +++ b/_Sidebar.md @@ -1,6 +1,7 @@ ### Introduction * [[Components]] * [[Getting Started]] +* [[Quick Start with weed mini]] * [[Production Setup]] * [[Benchmarks]] * [[FAQ]]