upstream-seaweedfs/test/s3/iam/README-Docker.md

SeaweedFS S3 IAM Integration with Docker Compose

This directory contains a complete Docker Compose setup for testing SeaweedFS S3 IAM integration with Keycloak OIDC authentication.

🚀 Quick Start

1. Build local SeaweedFS image:

   make -f Makefile.docker docker-build
   

2. Start the environment:

   make -f Makefile.docker docker-up
   

3. Run the tests:

   make -f Makefile.docker docker-test
   

4. Stop the environment:

   make -f Makefile.docker docker-down
   

📋 What's Included

The Docker Compose setup includes:

• 🔐 Keycloak - Identity provider with OIDC support
• 🎯 SeaweedFS Master - Metadata management
• 💾 SeaweedFS Volume - Data storage
• 📁 SeaweedFS Filer - File system interface
• 📊 SeaweedFS S3 - S3-compatible API with IAM integration
• 🔧 Keycloak Setup - Automated realm and user configuration

🌐 Service URLs

After starting with docker-up, services are available at:

Service	URL	Credentials
🔐 Keycloak Admin	http://localhost:8080	admin/admin
📊 S3 API	http://localhost:8333	JWT tokens
📁 Filer	http://localhost:8888	-
🎯 Master	http://localhost:9333	-

👥 Test Users

The setup automatically creates test users in Keycloak:

Username	Password	Role	Permissions
admin-user	adminuser123	s3-admin	Full S3 access
read-user	readuser123	s3-read-only	Read-only access
write-user	writeuser123	s3-read-write	Read and write
write-only-user	writeonlyuser123	s3-write-only	Write only

🧪 Running Tests

All Tests

make -f Makefile.docker docker-test

Specific Test Categories

# Authentication tests only
make -f Makefile.docker docker-test-auth

# Role mapping tests only  
make -f Makefile.docker docker-test-roles

# S3 operations tests only
make -f Makefile.docker docker-test-s3ops

Single Test

make -f Makefile.docker docker-test-single TEST_NAME=TestKeycloakAuthentication

🔧 Development Workflow

Complete workflow (recommended)

# Build, start, test, and clean up
make -f Makefile.docker docker-build
make -f Makefile.docker docker-dev

This runs: build → down → up → test

Using Published Images (Alternative)

If you want to use published Docker Hub images instead of building locally:

export SEAWEEDFS_IMAGE=chrislusf/seaweedfs:latest
make -f Makefile.docker docker-up

Manual steps

# Build image (required first time, or after code changes)
make -f Makefile.docker docker-build

# Start services
make -f Makefile.docker docker-up

# Watch logs
make -f Makefile.docker docker-logs

# Check status
make -f Makefile.docker docker-status

# Run tests
make -f Makefile.docker docker-test

# Stop services  
make -f Makefile.docker docker-down

🔍 Debugging

View logs

# All services
make -f Makefile.docker docker-logs

# S3 service only (includes role mapping debug)
make -f Makefile.docker docker-logs-s3  

# Keycloak only
make -f Makefile.docker docker-logs-keycloak

Get shell access

# S3 container
make -f Makefile.docker docker-shell-s3

# Keycloak container
make -f Makefile.docker docker-shell-keycloak

📁 File Structure

seaweedfs/test/s3/iam/
├── docker-compose.yml          # Main Docker Compose configuration
├── Makefile.docker             # Docker-specific Makefile
├── setup_keycloak_docker.sh    # Keycloak setup for containers
├── README-Docker.md            # This file
├── iam_config.json            # IAM configuration (auto-generated)
├── test_config.json           # S3 service configuration
└── *_test.go                  # Go integration tests

🔄 Configuration

IAM Configuration

The setup_keycloak_docker.sh script automatically generates iam_config.json with:

• OIDC Provider: Keycloak configuration with proper container networking
• Role Mapping: Maps Keycloak roles to SeaweedFS IAM roles
• Policies: Defines S3 permissions for each role
• Trust Relationships: Allows Keycloak users to assume SeaweedFS roles

Role Mapping Rules

{
  "claim": "roles",
  "value": "s3-admin", 
  "role": "arn:aws:iam::role/KeycloakAdminRole"
}

🐛 Troubleshooting

Services not starting

# Check service status
make -f Makefile.docker docker-status

# View logs for specific service
docker-compose -p seaweedfs-iam-test logs <service-name>

Keycloak setup issues

# Re-run Keycloak setup manually
make -f Makefile.docker docker-keycloak-setup

# Check Keycloak logs
make -f Makefile.docker docker-logs-keycloak

Role mapping not working

# Check S3 logs for role mapping debug messages
make -f Makefile.docker docker-logs-s3 | grep -i "role\|claim\|mapping"

Port conflicts

If ports are already in use, modify docker-compose.yml:

ports:
  - "8081:8080"  # Change external port

🧹 Cleanup

# Stop containers and remove volumes
make -f Makefile.docker docker-down

# Complete cleanup (containers, volumes, images)
make -f Makefile.docker docker-clean

🎯 Key Features

• Local Code Testing: Uses locally built SeaweedFS images to test current code
• Isolated Environment: No conflicts with local services
• Consistent Networking: Services communicate via Docker network
• Automated Setup: Keycloak realm and users created automatically
• Debug Logging: Verbose logging enabled for troubleshooting
• Health Checks: Proper service dependency management
• Volume Persistence: Data persists between restarts (until docker-down)

🚦 CI/CD Integration

For automated testing:

# Build image, run tests with proper cleanup
make -f Makefile.docker docker-build
make -f Makefile.docker docker-up
make -f Makefile.docker docker-wait-healthy  
make -f Makefile.docker docker-test
make -f Makefile.docker docker-down