.. | ||
dash | ||
handlers | ||
static | ||
view | ||
Makefile | ||
README.md |
SeaweedFS Admin Component
A modern web-based administration interface for SeaweedFS clusters built with Go, Gin, Templ, and Bootstrap.
Features
- Dashboard: Real-time cluster status and metrics
- Master Management: Monitor master nodes and leadership status
- Volume Server Management: View volume servers, capacity, and health
- Object Store Bucket Management: Create, delete, and manage Object Store buckets with web interface
- System Health: Overall cluster health monitoring
- Responsive Design: Bootstrap-based UI that works on all devices
- Authentication: Optional user authentication with sessions
- TLS Support: HTTPS support for production deployments
Building
Using the Admin Makefile
The admin component has its own Makefile for development and building:
# Navigate to admin directory
cd weed/admin
# View all available targets
make help
# Generate templates and build
make build
# Development mode with template watching
make dev
# Run the admin server
make run
# Clean build artifacts
make clean
Using the Root Makefile
The root SeaweedFS Makefile automatically integrates the admin component:
# From the root directory
make install # Builds weed with admin component
make full_install # Full build with all tags
make test # Runs tests including admin component
# Admin-specific targets from root
make admin-generate # Generate admin templates
make admin-build # Build admin component
make admin-run # Run admin server
make admin-dev # Development mode
make admin-clean # Clean admin artifacts
Manual Building
If you prefer to build manually:
# Install templ compiler
go install github.com/a-h/templ/cmd/templ@latest
# Generate templates
templ generate
# Build the main weed binary
cd ../../../
go build -o weed ./weed
Development
Template Development
The admin interface uses Templ for type-safe HTML templates:
# Watch for template changes and auto-regenerate
make watch
# Or manually generate templates
make generate
# Format templates
make fmt
File Structure
weed/admin/
├── Makefile # Admin-specific build tasks
├── README.md # This file
├── S3_BUCKETS.md # Object Store bucket management documentation
├── admin.go # Main application entry point
├── dash/ # Server and handler logic
│ ├── admin_server.go # HTTP server setup
│ ├── handler_admin.go # Admin dashboard handlers
│ ├── handler_auth.go # Authentication handlers
│ └── middleware.go # HTTP middleware
├── static/ # Static assets
│ ├── css/admin.css # Admin-specific styles
│ └── js/admin.js # Admin-specific JavaScript
└── view/ # Templates
├── app/ # Application templates
│ ├── admin.templ # Main dashboard template
│ ├── s3_buckets.templ # Object Store bucket management template
│ └── *_templ.go # Generated Go code
└── layout/ # Layout templates
├── layout.templ # Base layout template
└── layout_templ.go # Generated Go code
S3 Bucket Management
The admin interface includes comprehensive Object Store bucket management capabilities. See S3_BUCKETS.md for detailed documentation on:
- Creating and deleting Object Store buckets
- Viewing bucket contents and metadata
- Managing bucket permissions and settings
- API endpoints for programmatic access
Usage
Basic Usage
# Start admin interface on default port (23646)
weed admin
# Start with custom configuration
weed admin -port=8080 -masters="master1:9333,master2:9333"
# Start with authentication
weed admin -adminUser=admin -adminPassword=secret123
# Start with HTTPS
weed admin -port=443 -tlsCert=/path/to/cert.pem -tlsKey=/path/to/key.pem
Configuration Options
Option | Default | Description |
---|---|---|
-port |
23646 | Admin server port |
-masters |
localhost:9333 | Comma-separated master servers |
-adminUser |
admin | Admin username (if auth enabled) |
-adminPassword |
"" | Admin password (empty = no auth) |
-tlsCert |
"" | Path to TLS certificate |
-tlsKey |
"" | Path to TLS private key |
Docker Usage
# Build Docker image with admin component
make docker-build
# Run with Docker
docker run -p 23646:23646 seaweedfs/seaweedfs:latest admin -masters=host.docker.internal:9333
Development Workflow
Quick Start
# Clone and setup
git clone <seaweedfs-repo>
cd seaweedfs/weed/admin
# Install dependencies and build
make install-deps
make build
# Start development server
make dev
Making Changes
-
Template Changes: Edit
.templ
files inview/
- Templates auto-regenerate in development mode
- Use
make generate
to manually regenerate
-
Go Code Changes: Edit
.go
files- Restart the server to see changes
- Use
make build
to rebuild
-
Static Assets: Edit files in
static/
- Changes are served immediately
Testing
# Run admin component tests
make test
# Run from root directory
make admin-test
# Lint code
make lint
# Format code
make fmt
Production Deployment
Security Considerations
- Authentication: Always set
adminPassword
in production - HTTPS: Use TLS certificates for encrypted connections
- Firewall: Restrict admin interface access to authorized networks
Example Production Setup
# Production deployment with security
weed admin \
-port=443 \
-masters="master1:9333,master2:9333,master3:9333" \
-adminUser=admin \
-adminPassword=your-secure-password \
-tlsCert=/etc/ssl/certs/admin.crt \
-tlsKey=/etc/ssl/private/admin.key
Monitoring
The admin interface provides endpoints for monitoring:
GET /health
- Health check endpointGET /metrics
- Prometheus metrics (if enabled)GET /api/status
- JSON status information
Troubleshooting
Common Issues
- Templates not found: Run
make generate
to create template files - Build errors: Ensure
templ
is installed withmake install-templ
- Static files not loading: Check that
static/
directory exists and has proper files - Connection errors: Verify master and filer addresses are correct
Debug Mode
# Enable debug logging
weed -v=2 admin
# Check generated templates
ls -la view/app/*_templ.go view/layout/*_templ.go
Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
make test
- Format code:
make fmt
- Submit a pull request
Architecture
The admin component follows a clean architecture:
- Presentation Layer: Templ templates + Bootstrap CSS
- HTTP Layer: Gin router with middleware
- Business Logic: Handler functions in
dash/
package - Data Layer: Communicates with SeaweedFS masters and filers
This separation makes the code maintainable and testable.