Tom Butcher
ad8441f72f
All checks were successful
farmcontrol/farmcontrol-ws/pipeline/head This commit looks good
124 lines
2.6 KiB
Markdown
124 lines
2.6 KiB
Markdown
# FarmControl WebSocket Service
|
|
|
|
[](https://ci.tombutcher.work/job/farmcontrol/job/farmcontrol-ws/job/main/)
|
|
|
|
A WebSocket microservice for FarmControl that handles real-time communication and distributed locking.
|
|
|
|
## Features
|
|
|
|
- Real-time WebSocket communication
|
|
- Distributed locking
|
|
- Keycloak authentication integration
|
|
- MongoDB integration for user management
|
|
- Event streaming and notifications
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js (v16 or higher)
|
|
- MongoDB server
|
|
- Redis 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:
|
|
|
|
### 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"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Running the Application
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
## 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 (redis, mongo)
|
|
├── lock/ # Distributed locking
|
|
├── notification/ # Notification management
|
|
├── socket/ # WebSocket handling
|
|
└── index.js # Main application entry point
|
|
```
|
|
|
|
### Adding New Features
|
|
|
|
1. **Database operations**: Use the `redisServer` instance for Redis operations
|
|
2. **WebSocket events**: Extend the `SocketUser` class
|
|
3. **Authentication**: Extend the `KeycloakAuth` class
|
|
|
|
## Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
1. **Redis connection failed**: Ensure Redis 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`
|