Regolith

Rails for Distributed Systems

Regolith brings the elegance and developer experience of Rails to microservices architecture. Write cross-service associations like user.orders.create! and let Regolith handle the distributed complexity.

✨ Features

Zero-config service discovery - Services find each other automatically
ActiveRecord-style cross-service associations - user.orders.create! works across services
Docker orchestration built-in - One command starts your entire stack
Rails API scaffolding - Generate production-ready services in seconds
Hot reload development - Code changes reflect immediately in running containers
Rails console access - Debug any service with regolith console users

🚀 Quick Start

Installation

gem install regolith
Create your first distributed app
bash# Create new app
regolith new my-app
cd my-app

# Generate microservices
regolith generate service users
regolith generate service orders

# Start everything
regolith server
Your services are now running:

👥 users_service at http://localhost:3001
📦 orders_service at http://localhost:3002
🗄️ PostgreSQL at localhost:5432

🌟 Cross-Service Magic
Define relationships that span services:
ruby# users_service/app/models/user.rb
class User < Regolith::RegolithRecord
  service :users
  has_many :orders, service: :orders
end

# orders_service/app/models/order.rb
class Order < Regolith::RegolithRecord
  service :orders
  belongs_to :user, service: :users
end
Use them naturally:
ruby# In users_service Rails console
user = User.create!(name: "Alice", email: "[email protected]")
user.orders.create!(product: "iPhone", amount: 999)

# In orders_service Rails console  
order = Order.find(1)
order.user.name # "Alice" - fetched from users_service!
📁 Project Structure
my-app/
├── docker-compose.yml          # Orchestration config
├── config/
│   └── regolith.yml           # Service registry
├── services/
│   ├── users_service/         # Rails API app
│   └── orders_service/        # Rails API app
└── Makefile                   # Convenience commands
🛠️ CLI Commands
CommandPurposeregolith new <app>Create new Regolith applicationregolith generate service <name>Generate new microserviceregolith serverStart all services with Docker Composeregolith console <service>Open Rails console for serviceregolith versionShow version information
🏗️ How It Works
Service Discovery
Services are registered in config/regolith.yml:
yamlname: my-app
services:
  users:
    port: 3001
    root: ./services/users_service
  orders:
    port: 3002
    root: ./services/orders_service
Inter-Service Communication
The Regolith::RegolithRecord class extends ActiveModel with HTTP-based service calls:
rubyclass User < Regolith::RegolithRecord
  service :users
  has_many :orders, service: :orders
end
When you call user.orders.create!(), Regolith:

Identifies the target service (:orders)
Makes HTTP POST to orders_service/orders
Includes the foreign key (user_id)
Returns the created object

Docker Integration
Each service gets its own container with:

Hot reload via volume mounts
Shared PostgreSQL database
Inter-service networking
Environment-based configuration

🧪 Development Workflow
bash# Start all services
regolith server

# Open Rails console for any service
regolith console users

# Test cross-service relationships
User.first.orders.create!(product: "Laptop", amount: 1200)

# Check logs
docker-compose logs -f users

# Add new service
regolith generate service analytics
📦 Example: E-commerce Platform
bash# Create the platform
regolith new ecommerce
cd ecommerce

# Generate services
regolith generate service users
regolith generate service products  
regolith generate service orders
regolith generate service payments

# Start everything
regolith server
ruby# Define cross-service relationships
class User < Regolith::RegolithRecord
  service :users
  has_many :orders, service: :orders
end

class Order < Regolith::RegolithRecord
  service :orders
  belongs_to :user, service: :users
  belongs_to :product, service: :products
  has_one :payment, service: :payments
end

# Use like Rails
user = User.create!(name: "Bob", email: "[email protected]")
product = Product.create!(name: "MacBook", price: 2000)
order = user.orders.create!(product: product)
order.create_payment!(amount: 2000, method: "credit_card")
🔧 Configuration
Custom Service Configuration
ruby# config/initializers/regolith.rb
Regolith.configure do |config|
  config.timeout = 30
  config.retry_attempts = 3
end
Environment Variables
VariablePurposeREGOLITH_SERVICE_NAMECurrent service identifierREGOLITH_SERVICE_PORTService port mappingDATABASE_URLShared database connection
Production Deployment
For production, replace Docker Compose with:

Container orchestration: Kubernetes, ECS, or similar
Service mesh: Istio, Linkerd for advanced networking
Service discovery: Consul, etcd for dynamic registration
Load balancing: nginx, HAProxy for traffic distribution
Monitoring: Prometheus, Grafana for observability

📚 Examples
Working Observatory App
The repository includes a complete example in observatory/:

telescope_service - User management
records_service - Observation tracking
Full cross-service associations
Docker orchestration

More Examples

E-commerce Platform - Multi-service shopping platform
Social Network - Users, posts, and comments across services
Blog Platform - Authors, articles, and analytics services

🤝 Contributing
We love contributions! See CONTRIBUTING.md for guidelines.

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

🐛 Issues & Support

Bug reports: GitHub Issues
Feature requests: GitHub Discussions
Documentation: GitHub Wiki

📄 License
MIT License - see LICENSE for details.
🙏 Acknowledgments

Inspired by the elegance of Ruby on Rails
Built for the modern microservices era
Designed to make distributed systems feel human


Regolith: Because microservices shouldn't be micro-management.
Built with ❤️ for developers who want to focus on features, not infrastructure.