README
¶
Node Registrar Service
Overview
This project provides an API for registring and managing zos nodes on ThreeFold GridV4. Built with the Go Gin framework and PostgreSQL database, It offers operations like registring, listing, and updating farms and nodes, as well as reporting uptime and consumption data for nodes.
Features
-
Farm Management
- Create/update farms with owner authorization
- List farms with filtering/pagination
- Automatic twin ID association via authentication
-
Node Registration
- Create/update nodes with owner authorization
- Uptime reporting
- Node metadata management (location, interfaces, specs)
-
Account System
- ED25519/SR25519 authentication
- Relay management for RMB communication
-
Security
- Challenge-response authentication middleware
- Ownership verification for mutations
- Timestamp replay protection
Endpoint Descriptions
Farms Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /farms/ |
List all farms with optional filtering |
| GET | /farms/:farm_id |
Get a specific farm by ID |
| POST | /farms/ |
Create a new farm |
| PATCH | /farms/ |
Update an existing farm |
Nodes Endpoints
| Method | Endpoint | Description |
|---|---|---|
| GET | /nodes/ |
List all nodes with optional filtering |
| GET | /nodes/:node_id |
Get a specific node by ID |
| POST | /nodes/ |
Register a new node |
| POST | /nodes/:node_id/uptime |
Report uptime for a specific node |
| POST | /nodes/:node_id/consumption |
Report consumption for a specific node |
Setup Instructions
-
Start PostgreSQL:
make start-postgres -
Run the Server:
make run -
Stop PostgreSQL:
make stop-postgres
Swagger Documentation
Once the server is running, Swagger documentation can be accessed at:
http://<domain>:<port>/swagger/index.html
Replace <domain> and <port> with the appropriate values.
How to Use the Server
- Use a tool like Postman or cURL to interact with the API.
- Refer to the Swagger documentation for detailed information about request parameters and response structures.
How to run the server with docker
- To use the docker file to build the docker image, run this command in the root directory of the sdk
docker build -t registrar:latest -f node-registrar/Dockerfile .
-
run the image
docker run -d \ -p 8080:8080 \ --name registrar \ registrar:latest \ ./server --postgres-host=<your-postgres-host> \ --postgres-port=5432 \ --postgres-db=<your-db-name> \ --postgres-user=<your-db-user> \ --postgres-password=<your-db-password> \ --ssl-mode=disable \ --sql-log-level=2 \ --max-open-conn=10 \ --max-idle-conn=5 \ --server-port=8080 \ --<domain=your-domain> \ --network=main\ --admin_twin_id=1 --debug
Authentication
Requests requiring authorization must include:
X-Auth: Base64(Challenge):Base64(Signature)
Challenge Format:
<unix_timestamp>:<twin_id>
Signature: ED25519/SR25519 signature of challenge bytes
The service uses a PostgreSQL database with the following key tables:
| Table | Description |
|---|---|
accounts |
Authentication credentials and relay configurations |
farms |
Farm metadata with owner relationship |
nodes |
Node hardware specifications and resources |
uptime_reports |
Historical node availability data |
Development
Generating Swagger Docs
swag init -g pkg/server/handlers.go --output docs --parseDependency --parseDepth 2
Client Library
A Go client library is available to interact with the Node Registrar Service. See the client documentation for details on installation and usage.
Example usage:
import "github.com/threefoldtech/tfgrid-sdk-go/node-registrar/client"
// Initialize client
cli, err := client.NewRegistrarClient("https://registrar.dev.grid.tf", mnemonic)
// Register a node
node := Node{
TwinID: twinID,
FarmID: farmID,
Interfaces: interfaces,
Location: location,
Resources: resources,
SerialNumber: serialNumber,
SecureBoot: secureBoot,
Virtualized: virtualized,
}
nodeID, err := cli.RegisterNode(node)
Generating Swagger Documentation
swag init -g pkg/server/handlers.go --output docs --parseDependency --parseDepth 2
Running Tests
make test
Directories