Getting Started

This section explains the basic usage while introduces new users to Luna.

Monitoring Luna using the built-in panel

Luna has a built-in panel at the route /registry/v1/services/. This panel provides information about the services and the status of their instances. The panel is protected using basic access authentication as are all the routes.

Basic Auth Protection

You are not required to have a password however you will always have a username (default: admin). This means to access any route you will either embed the auth to the URL or login manually when you access it in the browser. The credentials are configurable through ENV variables as explained here.

For example, if you run a Luna registry at localhost:4000 which is the default port. To access the panel, you would have to login to the page using the default credential *(username: admin, password: (BLANK). Alternatively or when you are calling it from a service, you can embed the login to the URL, admin@localhost:4000/registry/v1/services.

Creating a new Service

Services are created when you register the first instance for that service.

Registering an instance

Instances have an instance id which is in the format serviceName:domain:port. To register an instance, send a POST request to the instance's endpoint with the instance's info. Instance's Info contents are listed here.

POST /registry/v1/instances/{instanceId} 
Content-Type: application/json
Body: {Instance Info Here}

Health checking instances

A Service is considered to be online if just one of its instances is OK. Luna does not check the instance's health from the server, rather depends on the instances to provide its status. This allows dynamic status changing from the client (ex. One of its main Databases is down, shutting down the instance).

To send a heartbeat to the registry, send a PUT request to the instance's endpoint with the instance's info.

PUT /registry/v1/instances/{instanceId} 
Content-Type: application/json
Body: {Instance Info Here}

An instance is considered DOWN if it's been 30 seconds since the last heartbeat.

Deregister an instance

Deregistering an instance will remove that instance from the registry. You should not do this unless the instance itself will no longer be available. If you only need to bring down the instance for a bit, consider changing the status through a heartbeat as mentioned in above.

To deregister an instance, send a DELETE request to the instance's endpoint.

DELETE /registry/v1/instances/{instanceId} 

More Examples

Basic TypeScript Example - Basic registration and sending heartbeats.

To-do App Article - Github Repo