178 lines
3.9 KiB
Markdown
178 lines
3.9 KiB
Markdown
# FarmControl WebSocket Service
|
|
|
|
A WebSocket microservice for FarmControl that handles real-time communication and distributed locking using etcd.
|
|
|
|
## Features
|
|
|
|
- Real-time WebSocket communication
|
|
- Distributed locking using etcd
|
|
- Keycloak authentication integration
|
|
- MongoDB integration for user management
|
|
- Event streaming and notifications
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js (v16 or higher)
|
|
- etcd server
|
|
- MongoDB server
|
|
- Keycloak server (for authentication)
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository
|
|
2. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The application uses `config.json` for configuration. Update the following sections:
|
|
|
|
### Etcd Configuration
|
|
```json
|
|
{
|
|
"database": {
|
|
"etcd": {
|
|
"host": "localhost",
|
|
"port": 2379
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### MongoDB Configuration
|
|
```json
|
|
{
|
|
"database": {
|
|
"mongo": {
|
|
"url": "mongodb://localhost:27017/farmcontrol"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Authentication Configuration
|
|
```json
|
|
{
|
|
"auth": {
|
|
"enabled": true,
|
|
"keycloak": {
|
|
"url": "https://your-keycloak-server",
|
|
"realm": "your-realm",
|
|
"clientId": "your-client-id",
|
|
"clientSecret": "your-client-secret"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Running the Application
|
|
|
|
### Development
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
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
|
|
|
|
The service exposes WebSocket endpoints for:
|
|
|
|
- **Lock management**: Lock/unlock objects with real-time notifications
|
|
- **Authentication**: Keycloak-based authentication
|
|
- **Real-time updates**: Stream-based event notifications
|
|
|
|
## Development
|
|
|
|
### Project Structure
|
|
```
|
|
src/
|
|
├── auth/ # Authentication logic
|
|
├── database/ # Database connections (etcd, mongo)
|
|
├── lock/ # Distributed locking
|
|
├── notification/ # Notification management
|
|
├── socket/ # WebSocket handling
|
|
└── index.js # Main application entry point
|
|
```
|
|
|
|
### Adding New Features
|
|
|
|
1. **Database operations**: Use the `etcdServer` instance for etcd operations
|
|
2. **WebSocket events**: Extend the `SocketClient` class
|
|
3. **Authentication**: Extend the `KeycloakAuth` class
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Etcd connection failed**: Ensure etcd is running on the configured host and port
|
|
2. **Authentication errors**: Verify Keycloak configuration and credentials
|
|
3. **MongoDB connection issues**: Check MongoDB server status and connection string
|
|
|
|
### Logging
|
|
|
|
The application uses log4js for logging. Set the log level in the configuration:
|
|
|
|
```json
|
|
{
|
|
"server": {
|
|
"logLevel": "debug"
|
|
}
|
|
}
|
|
```
|
|
|
|
Available log levels: `trace`, `debug`, `info`, `warn`, `error` |