Update readme

This commit is contained in:
Tom Butcher 2025-12-13 21:08:23 +00:00
parent 2fc477ab25
commit aa931c8f96

View File

@ -1,11 +1,11 @@
# FarmControl WebSocket Service # FarmControl WebSocket Service
A WebSocket microservice for FarmControl that handles real-time communication and distributed locking using etcd. A WebSocket microservice for FarmControl that handles real-time communication and distributed locking.
## Features ## Features
- Real-time WebSocket communication - Real-time WebSocket communication
- Distributed locking using etcd - Distributed locking
- Keycloak authentication integration - Keycloak authentication integration
- MongoDB integration for user management - MongoDB integration for user management
- Event streaming and notifications - Event streaming and notifications
@ -13,8 +13,8 @@ A WebSocket microservice for FarmControl that handles real-time communication an
## Prerequisites ## Prerequisites
- Node.js (v16 or higher) - Node.js (v16 or higher)
- etcd server
- MongoDB server - MongoDB server
- Redis server
- Keycloak server (for authentication) - Keycloak server (for authentication)
## Installation ## Installation
@ -29,19 +29,6 @@ A WebSocket microservice for FarmControl that handles real-time communication an
The application uses `config.json` for configuration. Update the following sections: The application uses `config.json` for configuration. Update the following sections:
### Etcd Configuration
```json
{
"database": {
"etcd": {
"host": "localhost",
"port": 2379
}
}
}
```
### MongoDB Configuration ### MongoDB Configuration
```json ```json
@ -84,59 +71,6 @@ npm run dev
npm start npm start
``` ```
## Etcd Setup
### Installation
#### Using Docker
```bash
docker run -d --name etcd \
-p 2379:2379 \
-p 2380:2380 \
quay.io/coreos/etcd:v3.5.0 \
/usr/local/bin/etcd \
--advertise-client-urls http://0.0.0.0:2379 \
--listen-client-urls http://0.0.0.0:2379
```
#### Using Homebrew (macOS)
```bash
brew install etcd
etcd
```
#### Using apt (Ubuntu/Debian)
```bash
sudo apt-get install etcd
sudo systemctl start etcd
```
### Verification
Test that etcd is running:
```bash
curl http://localhost:2379/version
```
## Migration from Redis
This application was migrated from Redis to etcd. The main changes include:
1. **Stream-like functionality**: Redis streams are replaced with etcd key-value pairs using a prefix pattern
2. **Hash-like functionality**: Redis hashes are replaced with etcd key-value pairs using a prefix pattern
3. **Pub/Sub**: Redis pub/sub is replaced with etcd watchers
4. **Connection management**: Simplified connection handling with automatic reconnection
### Key Differences
- **Data structure**: etcd uses a flat key-value store, so we simulate Redis data structures using key prefixes
- **Streams**: Instead of Redis streams, we use etcd keys with timestamps and random suffixes
- **Watching**: etcd watchers provide real-time notifications for key changes
- **Transactions**: etcd supports atomic operations for distributed locking
## API Endpoints ## API Endpoints
@ -153,7 +87,7 @@ The service exposes WebSocket endpoints for:
``` ```
src/ src/
├── auth/ # Authentication logic ├── auth/ # Authentication logic
├── database/ # Database connections (etcd, mongo) ├── database/ # Database connections (redis, mongo)
├── lock/ # Distributed locking ├── lock/ # Distributed locking
├── notification/ # Notification management ├── notification/ # Notification management
├── socket/ # WebSocket handling ├── socket/ # WebSocket handling
@ -162,7 +96,7 @@ src/
### Adding New Features ### Adding New Features
1. **Database operations**: Use the `etcdServer` instance for etcd operations 1. **Database operations**: Use the `redisServer` instance for Redis operations
2. **WebSocket events**: Extend the `SocketUser` class 2. **WebSocket events**: Extend the `SocketUser` class
3. **Authentication**: Extend the `KeycloakAuth` class 3. **Authentication**: Extend the `KeycloakAuth` class
@ -170,7 +104,7 @@ src/
### Common Issues ### Common Issues
1. **Etcd connection failed**: Ensure etcd is running on the configured host and port 1. **Redis connection failed**: Ensure Redis is running on the configured host and port
2. **Authentication errors**: Verify Keycloak configuration and credentials 2. **Authentication errors**: Verify Keycloak configuration and credentials
3. **MongoDB connection issues**: Check MongoDB server status and connection string 3. **MongoDB connection issues**: Check MongoDB server status and connection string