Skip to content

README.md

Latest commit

 

History

History
219 lines (161 loc) · 7.43 KB

README.md

File metadata and controls

219 lines (161 loc) · 7.43 KB
Raw

GitHub Workflow Status (branch) GoDoc Coverage Status Supported Go Versions GitHub Release Go Report Card

kratos-supervisordrun

Go package to generate supervisord configuration with Kratos microservices integration.

CHINESE README

中文说明

Main Features

🎯 Fluent Configuration API: Chain methods to build supervisord config ⚡ Kratos Integration: Optimized configuration patterns to run Kratos microservices 🔄 Group Management: Multi-program groups with centralized configuration 🌍 Tested Configuration: Battle-tested templates that run high-performance services 📋 Strong Typing: Typed configuration with sensible defaults

Installation

go get github.com/yylego/kratos-supervisordrun/supervisordrunkratos

Usage

Single Program Configuration

package main

import (
    "fmt"
    "github.com/yylego/kratos-supervisordrun/supervisordrunkratos"
)

func main() {
    // Create program config with required parameters
    program := supervisordrunkratos.NewProgramConfig(
        "myapp",           // Program name
        "/opt/myapp",      // Program root DIR
        "deploy",          // User name
        "/var/log/myapp",  // Log DIR
    ).WithStartRetries(10).
      WithEnvironment(map[string]string{
          "APP_ENV": "production",
      })

    // Generate configuration
    config := supervisordrunkratos.GenerateProgramConfig(program)
    fmt.Println(config)
}

Group Configuration

// Create multiple programs
apiServer := supervisordrunkratos.NewProgramConfig(
    "api-server", "/opt/api-server", "deploy", "/var/log/services",
).WithStartRetries(3)

worker := supervisordrunkratos.NewProgramConfig(
    "worker", "/opt/worker", "deploy", "/var/log/services",
).WithAutoStart(false)

// Create group
group := supervisordrunkratos.NewGroupConfig("microservices").
    AddProgram(apiServer).
    AddProgram(worker)

config := supervisordrunkratos.GenerateGroupConfig(group)

Advanced Configuration

// High-performance service configuration
program := supervisordrunkratos.NewProgramConfig(
    "high-perf", "/opt/high-perf", "performance", "/var/log/perf",
).WithStartRetries(100).
  WithStopWaitSecs(60).
  WithLogMaxBytes("500MB").
  WithLogBackups(50).
  WithPriority(1)

Multi-Instance Deployment

// Multi-instance web server
program := supervisordrunkratos.NewProgramConfig(
    "web-server", "/opt/web-server", "deploy", "/var/log/cluster",
).WithNumProcs(3).
  WithProcessName("%(program_name)s_%(process_num)02d").
  WithEnvironment(map[string]string{
      "PORT_BASE": "8080",
  })

Configuration Options

Process Settings

  • WithAutoStart(bool) - Auto start on supervisord startup
  • WithAutoRestart(bool) - Auto restart on crash
  • WithAutoRestartMode(string) - Auto restart mode ("false"/"true"/"unexpected")
  • WithStartRetries(int) - Max start attempts count
  • WithStartSecs(int) - Wait time in seconds before start succeeds

Logging

  • WithLogMaxBytes(string) - Max log file size (e.g., "50MB", "1GB")
  • WithLogBackups(int) - Log backup files count
  • WithRedirectStderr(bool) - Redirect stderr to stdout

Process Execution

  • WithStopWaitSecs(int) - Clean stop timeout seconds
  • WithStopSignal(string) - Stop command name (TERM, INT, QUIT)
  • WithKillAsGroup(bool) - Terminate child processes as group
  • WithPriority(int) - Start rank (low ranks start first)

Multi-Instance

  • WithNumProcs(int) - Count of process instances
  • WithProcessName(string) - Process name template

Environment

  • WithEnvironment(map[string]string) - Environment setting
  • WithExitCodes([]int) - Expected exit codes

Recommended Workflow

# 1. Generate config file
go run main.go > /etc/supervisord/conf.d/myapp.conf

# 2. Reload supervisord
sudo supervisorctl reread
sudo supervisorctl update

# 3. Manage services
sudo supervisorctl start myapp
sudo supervisorctl status

📄 License

MIT License - see LICENSE.

💬 Contact & Feedback

Contributions are welcome! Report bugs, suggest features, and contribute code:

  • 🐛 Mistake reports? Open an issue on GitHub with reproduction steps
  • 💡 Fresh ideas? Create an issue to discuss
  • 📖 Documentation confusing? Report it so we can improve
  • 🚀 Need new features? Share the use cases to help us understand requirements
  • ⚡ Performance issue? Help us optimize through reporting slow operations
  • 🔧 Configuration problem? Ask questions about complex setups
  • 📢 Follow project progress? Watch the repo to get new releases and features
  • 🌟 Success stories? Share how this package improved the workflow
  • 💬 Feedback? We welcome suggestions and comments

🔧 Development

New code contributions, follow this process:

  1. Fork: Fork the repo on GitHub (using the webpage UI).
  2. Clone: Clone the forked project (git clone https://github.com/yourname/kratos-supervisordrun.git).
  3. Navigate: Navigate to the cloned project (cd kratos-supervisordrun)
  4. Branch: Create a feature branch (git checkout -b feature/xxx).
  5. Code: Implement the changes with comprehensive tests
  6. Testing: (Golang project) Ensure tests pass (go test ./...) and follow Go code style conventions
  7. Documentation: Update documentation to support client-facing changes
  8. Stage: Stage changes (git add .)
  9. Commit: Commit changes (git commit -m "Add feature xxx") ensuring backward compatible code
  10. Push: Push to the branch (git push origin feature/xxx).
  11. PR: Open a merge request on GitHub (on the GitHub webpage) with detailed description.

Please ensure tests pass and include relevant documentation updates.

🌟 Support

Welcome to contribute to this project via submitting merge requests and reporting issues.

Project Support:

  • ⭐ Give GitHub stars if this project helps you
  • 🤝 Share with teammates and (golang) programming friends
  • 📝 Write tech blogs about development tools and workflows - we provide content writing support
  • 🌟 Join the ecosystem - committed to supporting open source and the (golang) development scene

Have Fun Coding with this package! 🎉🎉🎉

GitHub Stars

Stargazers