Add /health endpoint for comprehensive service readiness checking

[Copilot]

This PR adds a new /health endpoint that provides a simple way to determine when the Stellar Quickstart image is fully ready for use, addressing the issue where users need to write custom scripts to test readiness.

Changes

New /health Endpoint

• HTTP 200 when all services are ready for use
• HTTP 503 when any service is not ready
• JSON response with detailed service status

Example response when ready:

{
  "status": "ready",
  "services": {
    "stellar-core": "ready",
    "horizon": "ready",
    "horizon_health": {
      "database_connected": true,
      "core_up": true,
      "core_synced": true
    },
    "stellar-rpc": "ready"
  }
}

Implementation Details

• Auto-detection: Automatically detects which services are actually running
• Smart health checks: Uses appropriate health check methods for each service:
  • stellar-core: /info endpoint
  • horizon: Root endpoint + ingestion status + built-in /health
  • stellar-rpc: getHealth JSON-RPC method
• Replaces Horizon's health endpoint: The new /health endpoint sits over Horizon's original health endpoint, providing comprehensive service status
• Comprehensive: Only reports "ready" when ALL detected services are functioning

Architecture

• Python-based service running on internal port 8004
• nginx proxy routes /health through main port 8000
• supervisord management ensures service reliability
• Integrated with start script for proper deployment

Documentation

• Added comprehensive endpoint documentation with examples
• Updated ports table to include readiness service
• Explained how the new /health endpoint provides comprehensive status for all services

Testing

Verified working with test container running --local --enable core,horizon,rpc:

• ✅ All three services detected and reported as ready
• ✅ HTTP 200 status when ready
• ✅ Proper JSON response format through nginx on port 8000
• ✅ CI tests pass with proper endpoint access

This eliminates the need for users to write custom scripts to test multiple service endpoints individually.

Fixes #683.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[leighmcculloch]

Can the endpoint be /health?

[leighmcculloch]

It's fine for the /health endpoint to sit over Horizon's health endpoint.

[sagpatil]

@copilot can you rename the endpoint to /health

[Copilot]

@copilot can you rename the endpoint to /health

Done! Renamed the endpoint from /ready to /health as requested. The changes include updating nginx configuration, Python service, documentation, and tests. Commit f4e78bb.

[leighmcculloch]

@sagpatil @fnando There was a discussion offline at https://stellarfoundation.slack.com/archives/C06KTGUULUF/p1752530679018619 where I shared the idea that we think about the root URL as the health endpoint. For the most part that's what it is for horizon historically, and as a user it's where I go when I want to see that the image is working. When Horizon is removed from being by default on, we should rethink the root path and what it serves, and a status / health like endpoint, like what horizon does today, could make sense.

[sagpatil]

@copilot resolve the minor conflicts in the code and run the tests again and fix if there are any errors.

[Copilot]

@copilot resolve the minor conflicts in the code and run the tests again and fix if there are any errors.

Conflicts resolved and tests verified! Fixed merge conflicts with main branch and corrected a typo in build-testing.yml. All code compiles successfully and the /health endpoint implementation is ready. Commit c77de6f.

[sagpatil]

@leighmcculloch good to merge ?

[sagpatil]

@copilot fix the failing test for health endpoint . It works locally but fails in ci , is local host accessible in docker

[Copilot]

@copilot fix the failing test for health endpoint . It works locally but fails in ci , is local host accessible in docker

Fixed the failing CI test! The issue was that the test was trying to access the internal readiness service directly on port 8004, but it should be testing the /health endpoint through nginx on port 8000. Updated the test to use http://127.0.0.1:8000/health and cleaned up the debugging code. The test now properly validates the complete health check pipeline. Commit eae11d3.

[leighmcculloch]

I think we should revisit this when horizon becomes optional and find a way to integrate this with the root url, since when horizon is optional we will still probably want to serve something on the root url, and maybe we can merge the health stuff with it so those fields are always present.