A simple decentralized metaverse where all users (Plaggones) gather in the Agora to chat and interact with each other. Production-ready with Docker containerization and Kubernetes orchestration.
look at this project soon, or not so soon...
The start for something unique.
plaggona, is the same metaphor for Greek as avatar in game/movies, not so as Hindu meaning, but you get the point.
The project aim to setup an infrastructure to hold plaggonas activities in metaverse worlds.
keep track of the digital memories while your plaggona lives on metaverse world, learning from what plaggona says, what action do, the behavior and the acts, keep all that for you referense and later when the plaggona matures bring it alive!
using advance monitoring while you use and act with your plaggona on metaverse world.
- 3D Virtual World: Immersive environment rendered with Three.js and WebGL
- Real-time Multiplayer: Seamless interaction using Socket.IO WebSockets
- Character System: Plaggona avatars with customizable variants (cloth colors)
- Identity System: Nickname labels displayed above characters
- Chat System: Real-time communication with commands and notifications
- Gesture System: Interactive character animations (wave, jump, dance)
- Responsive Design: Optimized for desktop and mobile devices
- Production Ready: Docker containerization with Kubernetes deployment
- Backend: Node.js 18 with Express.js
- Real-time Communication: Socket.IO with WebSocket fallbacks
- 3D Graphics: Three.js with WebGL acceleration
- Frontend: Modern JavaScript (ES6 modules)
- Styling: CSS3 with Grid, Flexbox, and animations
- Containerization: Docker with Alpine Linux
- Orchestration: Kubernetes with Helm charts
- Production Features: HPA, health checks, TLS, monitoring
-
Clone and install:
git clone <repository-url> cd plaggona-metaverse npm install
-
Start development server:
npm run dev # or ./dev.sh -
Open browser: Navigate to
http://localhost:3000
-
Build container:
docker build -t plaggona-metaverse . -
Run container:
docker run -p 3000:3000 plaggona-metaverse
For full production deployment with Kubernetes, see DEPLOYMENT.md
./deploy.shThis automated script handles:
- Docker image building and registry push
- Helm chart packaging
- Kubernetes deployment with high availability
- Health check verification
- Auto-scaling configuration
When you run more than one replica, each pod maintains its own in-memory user/room state. Without a pub/sub adapter, users connected to different pods won’t see each other. To enable a shared Agora across pods:
- Deploy Redis accessible from the app pods. This repo includes a simple Redis chart:
# Install Redis with a stable service name 'plagona-redis' helm upgrade --install plagona-redis ./charts/plagona-redis \ --set fullnameOverride=plagona-redis- With password and persistence:
helm upgrade --install plagona-redis ./charts/plagona-redis \ --set fullnameOverride=plagona-redis \ --set auth.enabled=true --set auth.password='<strong-password>' \ --set persistence.enabled=true --set persistence.size=1Gi
- With password and persistence:
- Set
REDIS_URLin the app chart:- Without auth:
helm upgrade --install plaggona ./charts/plaggona-k8s \ --set env.REDIS_URL=redis://plagona-redis:6379 \ --set autoscaling.enabled=true
- With auth:
helm upgrade --install plaggona ./charts/plaggona-k8s \ --set env.REDIS_URL="redis://:<strong-password>@plagona-redis:6379" \ --set autoscaling.enabled=true
- Without auth:
- The server will auto-enable the Socket.IO Redis adapter when
REDIS_URLis set (see logs below).
For debugging or single-node mode, disable autoscaling in charts/plaggona-k8s/values.yaml (autoscaling.enabled: false) and keep replicaCount: 1.
Server logs will indicate adapter status:
🔌 Socket.IO Redis adapter enabled– using Redis across podsℹ️ REDIS_URL not set...– single-pod mode⚠️ Redis adapter packages not installed– dependencies missing
Tip: To avoid committing secrets in values, you can template env.REDIS_URL from a Secret and reference it as an env var in the Deployment; the app will read process.env.REDIS_URL at startup.
- Enter your nickname when prompted
- Choose your cloth color for character customization
- Move around the Agora using WASD keys or arrow keys
- Chat with other Plaggones using the chat interface
- Use gestures by clicking the gesture buttons (wave, jump, dance)
- Interact with other players in real-time
plaggona-metaverse/
├── server.js # Express server with Socket.IO
├── package.json # Dependencies and scripts
├── Dockerfile # Production container config
├── deploy.sh # Kubernetes deployment script
├── dev.sh # Development startup script
├── public/
│ ├── index.html # Main application interface
│ ├── style.css # Comprehensive styling
│ └── js/
│ ├── metaverse.js # Main client controller
│ ├── world3d.js # Three.js 3D world renderer
│ ├── chat.js # Real-time chat system
│ └── ui.js # UI management and interactions
├── charts/plaggona-k8s/ # Kubernetes Helm charts
│ ├── Chart.yaml # Helm chart metadata
│ ├── values.yaml # Configuration values
│ └── templates/ # Kubernetes manifests
│ ├── deployment.yaml
│ ├── service.yaml
│ ├── ingress.yaml
│ └── hpa.yaml # Horizontal Pod Autoscaler
└── plaggona.jpeg # Character texture asset
- Express.js HTTP server
- Socket.IO real-time WebSocket communication
- User Management with session handling
- Room System for scalable multiplayer
- Chat Commands processing and response
- Health Checks for Kubernetes readiness
- MetaverseClient: Main application controller
- World3D: Three.js scene management and rendering
- ChatSystem: Real-time messaging with commands
- UIManager: Interface interactions and responsive design
- Multi-stage Build: Optimized production image
- Alpine Linux Base: Minimal attack surface (~50MB)
- Security Hardening: Non-root user execution
- Health Monitoring: Built-in container health checks
- High Availability: Auto-scaling 2-10 pods
- Load Balancing: Service mesh with health probes
- TLS Termination: SSL/TLS with Let's Encrypt
- WebSocket Support: Traefik ingress middleware
GET /api/users- List of online users with metadataGET /api/health- Health check for load balancersGET /api/rooms- Available rooms and user countsPOST /api/users- User registration endpoint
user_joined- New user connection notificationuser_left- User disconnection notificationuser_moved- Real-time position updateschat_message- Chat message broadcastgesture_performed- Character gesture animationsroom_changed- Room switching events
/help- Show available commands and features/who- List all online users with details/clear- Clear local chat history/time- Display current server time/rooms- Show available rooms/join <room>- Switch to different room
NODE_ENV=production # Runtime environment
PORT=3000 # Server port
LOG_LEVEL=info # Logging verbosity
MAX_USERS=1000 # Connection limit
CHAT_HISTORY_LIMIT=100 # Message retentionresources:
limits:
cpu: 500m
memory: 512Mi
requests:
cpu: 200m
memory: 256Mi
autoscaling:
enabled: true
minReplicas: 2
maxReplicas: 10
targetCPUUtilizationPercentage: 70- Startup Time: < 30 seconds to ready state
- Memory Usage: 256-512MB per pod instance
- CPU Usage: 200-500m per pod under load
- Concurrent Users: 100-500 per pod instance
- API Response Time: < 100ms for endpoints
- WebSocket Latency: < 50ms for real-time events
- Horizontal Scaling: Auto-scales based on CPU/memory
- Load Distribution: Even distribution across pods
- Session Stickiness: Not required (stateless design)
- Database: In-memory (Redis/external DB ready)
# Install dependencies
npm install
# Start development server with hot reload
npm run dev
# Run tests (when available)
npm test
# Build for production
npm run build# Build development image
docker build -t plaggona-dev .
# Run with volume mounting for live updates
docker run -v $(pwd):/app -p 3000:3000 plaggona-dev# Deploy to development namespace
microk8s.helm3 install plaggona-dev ./charts/plaggona-k8s \
--namespace dev --create-namespace \
--set image.tag=dev \
--set replicaCount=1The included deploy.sh script provides one-click production deployment:
./deploy.shFor detailed production deployment instructions, see DEPLOYMENT.md
- SSL certificates configured and validated
- Domain DNS pointing to Kubernetes cluster
- Resource limits appropriate for expected load
- Monitoring and alerting configured
- Backup strategy implemented
- Security contexts properly configured
- Health checks responding correctly
- Load testing completed
- Disaster recovery plan documented
- Non-root execution with dedicated user (plaggona:1001)
- Read-only root filesystem compatibility
- Minimal base image (Alpine Linux)
- Security scanning ready for CI/CD
- Pod Security Context with security constraints
- Network Policies for traffic isolation
- RBAC with minimal service account permissions
- Secrets Management for sensitive configuration
- Input validation for all user inputs
- XSS protection with content security policy
- Rate limiting for API endpoints
- WebSocket authentication and authorization
- Fork the repository and create a feature branch
- Follow coding standards and add tests
- Test locally with
npm run dev - Test with Docker using
docker build - Submit a Pull Request with clear description
- ESLint configuration for JavaScript
- Prettier for code formatting
- JSDoc for function documentation
- Semantic commits for change history
This project is open source and available under the MIT License.
- Documentation: See DEPLOYMENT.md for deployment details
- Issues: Use GitHub Issues for bug reports and feature requests
- Email: panagiotis@skarvelis.gr for deployment support
- Monitoring: Health checks available at
/api/health
🌍 Welcome to the production-ready Plaggona Metaverse! 🚀
Deployed with Docker + Kubernetes for enterprise-scale metaverse experiences