Edit README.md

README.md

-# ENACT Dataspace API - Setup & Deployment Guide
+# ENACT Dataspace API
+
 
 A multi-tenant EDC (Eclipse Dataspace Connector) API for managing dataspace connectors, assets, and data exchange workflows with Keycloak authentication.
 
 ## 📋 Prerequisites
 
-- Docker & Docker Compose
-- Linux/Unix environment
-- Domain name (for production)
-- SSL certificates (for production)
-- Keycloak instance (for authentication)
+- **Docker & Docker Compose** - Container orchestration
+- **Linux/Unix environment** - Development and deployment
+- **Domain name** - For production deployment
+- **SSL certificates** - HTTPS configuration
+- **Keycloak instance** - Authentication provider
 
 ## 🏗️ Project Structure
+
+```
 enact-dataspace/
 ├── app/                          # Node.js application
 │   ├── app.js                   # Main application file
@@ -28,6 +31,7 @@ enact-dataspace/
 ├── docker-compose.production.yml # Production container setup
 ├── .env                        # Production environment variables
 └── logs/                       # Application logs
+```
 
 ## 🚀 Quick Start
 
@@ -41,12 +45,21 @@ cd enact-dataspace
 # Create required directories
 mkdir -p logs ssl
 chmod 755 logs ssl
-2. Environment Configuration
-Create your .env file in the root directory:
-bashcp .env.production .env
+```
+
+### 2. Environment Configuration
+
+Create your `.env` file in the root directory:
+
+```bash
+cp .env.production .env
 nano .env
-Required Environment Variables:
-bash# Security & Encryption
+```
+
+#### Required Environment Variables
+
+```bash
+# Security & Encryption
 ENCRYPTION_KEY=<64-character-hex-key>  # Generate with: openssl rand -hex 32
 SESSION_SECRET=<base64-session-secret>
 EDC_WEBHOOK_SECRET=<webhook-secret>
@@ -71,17 +84,26 @@ DOMAIN=your-domain.com
 PROTOCOL=https
 DISABLE_AUTH=false
 MULTI_TENANT_MODE=true
-3. SSL Certificates (Production)
-Place your SSL certificates in the ssl/ directory:
-bash# Copy your certificates
+```
+
+### 3. SSL Certificates (Production)
+
+Place your SSL certificates in the `ssl/` directory:
+
+```bash
+# Copy your certificates
 cp your-fullchain.pem ssl/fullchain.pem
 cp your-private-key.pem ssl/privkey.pem
 
 # Set correct permissions
 chmod 644 ssl/fullchain.pem
 chmod 600 ssl/privkey.pem
-4. Deploy with Docker Compose
-bash# Create symlink for easier management
+```
+
+### 4. Deploy with Docker Compose
+
+```bash
+# Create symlink for easier management
 ln -sf docker-compose.production.yml docker-compose.yml
 
 # Start all services
@@ -92,10 +114,16 @@ docker-compose ps
 
 # View logs
 docker-compose logs -f enact-api
-🛠️ Development Setup
-Local Development with Authentication Disabled
-Create a development .env file:
-bash# Development configuration
+```
+
+## 🛠️ Development Setup
+
+### Local Development with Authentication Disabled
+
+Create a development `.env` file:
+
+```bash
+# Development configuration
 NODE_ENV=development
 PORT=3000
 DOMAIN=localhost
@@ -108,8 +136,12 @@ MULTI_TENANT_MODE=true
 # Use localhost endpoints for development
 MINIO_ENDPOINT=localhost
 KEYCLOAK_URL=https://your-keycloak-instance.com
-Running Development Mode
-bash# Install dependencies
+```
+
+### Running Development Mode
+
+```bash
+# Install dependencies
 cd app
 npm install
 
@@ -121,41 +153,64 @@ npm start
 
 # Or run everything in containers
 docker-compose -f docker-compose.simple.yml up -d
-🔧 Configuration Details
-Environment Variables Reference
-VariableDescriptionRequiredDefaultENCRYPTION_KEYAES-256 encryption key (64 hex chars)✅-KEYCLOAK_URLKeycloak server URL✅-KEYCLOAK_CLIENT_SECRETOAuth client secret✅-DATABASE_URLPostgreSQL connection string✅-DISABLE_AUTHDisable authentication for development❌falseMULTI_TENANT_MODEEnable multi-tenant EDC support❌trueLOG_LEVELLogging level (debug/info/warn/error)❌info
-Port Configuration
-ServiceInternal PortExternal PortDescriptionAPI30003000Main application APINginx80/44380/443Reverse proxy & SSL terminationPostgreSQL54325433Database (external for debugging)MinIO9000/9001-Object storage (internal only)
-🔐 Authentication Setup
-Keycloak Configuration
+```
+
+## 🔧 Configuration Details
+
+### Environment Variables Reference
+
+| Variable | Description | Required | Default |
+|----------|-------------|----------|---------|
+| `ENCRYPTION_KEY` | AES-256 encryption key (64 hex chars) | ✅ | - |
+| `KEYCLOAK_URL` | Keycloak server URL | ✅ | - |
+| `KEYCLOAK_CLIENT_SECRET` | OAuth client secret | ✅ | - |
+| `DATABASE_URL` | PostgreSQL connection string | ✅ | - |
+| `DISABLE_AUTH` | Disable authentication for development | ❌ | `false` |
+| `MULTI_TENANT_MODE` | Enable multi-tenant EDC support | ❌ | `true` |
+| `LOG_LEVEL` | Logging level (debug/info/warn/error) | ❌ | `info` |
+
+### Port Configuration
+
+| Service | Internal Port | External Port | Description |
+|---------|---------------|---------------|-------------|
+| API | 3000 | 3000 | Main application API |
+| Nginx | 80/443 | 80/443 | Reverse proxy & SSL termination |
+| PostgreSQL | 5432 | 5433 | Database (external for debugging) |
+| MinIO | 9000/9001 | - | Object storage (internal only) |
 
-Create Realm: Set up a realm in your Keycloak instance
-Create Client: Configure OAuth2 client with:
+## 🔐 Authentication Setup
 
-Client ID: connector-1 (or your chosen ID)
-Access Type: confidential
-Valid Redirect URIs: https://your-domain.com/*
-Web Origins: https://your-domain.com
+### Keycloak Configuration
 
+1. **Create Realm**: Set up a realm in your Keycloak instance
+2. **Create Client**: Configure OAuth2 client with:
+   - **Client ID**: `connector-1` (or your chosen ID)
+   - **Access Type**: confidential
+   - **Valid Redirect URIs**: `https://your-domain.com/*`
+   - **Web Origins**: `https://your-domain.com`
+3. **Client Credentials**: Note the client secret for your `.env` file
 
-Client Credentials: Note the client secret for your .env file
+### Token Verification
 
-Token Verification
 The application supports multiple authentication methods:
 
-Keycloak JWT tokens (production)
-API keys (service-to-service)
-Disabled auth (development only)
+- **Keycloak JWT tokens** (production)
+- **API keys** (service-to-service)
+- **Disabled auth** (development only)
 
-🗄️ Database Setup
-Automatic Initialization
-The database schema is automatically created on first run using scripts in init-scripts/:
+## 🗄️ Database Setup
 
-01-init-db.sql - Basic tables and indexes
-02-seed-data.sql - Initial data (if needed)
+### Automatic Initialization
 
-Manual Database Management
-bash# Connect to database
+The database schema is automatically created on first run using scripts in `init-scripts/`:
+
+- `01-init-db.sql` - Basic tables and indexes
+- `02-seed-data.sql` - Initial data (if needed)
+
+### Manual Database Management
+
+```bash
+# Connect to database
 docker-compose exec postgres psql -U enact_user -d enact_dataspace
 
 # Backup database
@@ -163,27 +218,35 @@ docker-compose exec postgres pg_dump -U enact_user enact_dataspace > backup.sql
 
 # Restore database
 docker-compose exec -T postgres psql -U enact_user -d enact_dataspace < backup.sql
-🌐 Nginx Configuration
-SSL/TLS Setup
+```
+
+## 🌐 Nginx Configuration
+
+### SSL/TLS Setup
+
 The included nginx configuration provides:
 
-SSL termination with modern TLS settings
-HTTP to HTTPS redirection
-Security headers (HSTS, CSP, etc.)
-Rate limiting for API endpoints
-Reverse proxy to Node.js application
+- SSL termination with modern TLS settings
+- HTTP to HTTPS redirection
+- Security headers (HSTS, CSP, etc.)
+- Rate limiting for API endpoints
+- Reverse proxy to Node.js application
+
+### Custom Nginx Configuration
 
-Custom Nginx Configuration
-Edit nginx/nginx.conf to customize:
+Edit `nginx/nginx.conf` to customize:
 
-Rate limiting rules
-Security headers
-Proxy settings
-SSL cipher suites
+- Rate limiting rules
+- Security headers
+- Proxy settings
+- SSL cipher suites
 
-📊 Monitoring & Maintenance
-Health Checks
-bash# Application health
+## 📊 Monitoring & Maintenance
+
+### Health Checks
+
+```bash
+# Application health
 curl https://your-domain.com/health
 
 # Database health
@@ -191,8 +254,12 @@ docker-compose exec postgres pg_isready -U enact_user
 
 # Container status
 docker-compose ps
-Log Management
-bash# View application logs
+```
+
+### Log Management
+
+```bash
+# View application logs
 docker-compose logs enact-api
 
 # View nginx logs
@@ -203,8 +270,12 @@ docker-compose logs -f
 
 # Log rotation (recommended for production)
 # Configure logrotate for docker logs
-Backup Strategy
-bash#!/bin/bash
+```
+
+### Backup Strategy
+
+```bash
+#!/bin/bash
 # backup.sh - Regular backup script
 
 # Backup database
@@ -215,9 +286,14 @@ cp .env "env-backup-$(date +%Y%m%d)"
 
 # Backup SSL certificates
 tar -czf "ssl-backup-$(date +%Y%m%d).tar.gz" ssl/
-🚦 API Usage
-Multi-Tenant EDC Management
-bash# Register a new EDC connector
+```
+
+## 🚦 API Usage
+
+### Multi-Tenant EDC Management
+
+```bash
+# Register a new EDC connector
 curl -X POST https://your-domain.com/api/connectors/register \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
@@ -237,8 +313,12 @@ curl -H "Authorization: Bearer $TOKEN" \
 # Health check all connectors
 curl -X POST -H "Authorization: Bearer $TOKEN" \
   https://your-domain.com/api/connectors/health
-Data Exchange Workflow
-bash# Complete workflow example
+```
+
+### Data Exchange Workflow
+
+```bash
+# Complete workflow example
 curl -X POST https://your-domain.com/api/v1/data-exchange/complete-workflow \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
@@ -250,10 +330,16 @@ curl -X POST https://your-domain.com/api/v1/data-exchange/complete-workflow \
     "description": "Test data exchange",
     "dataUrl": "https://api.example.com/data"
   }'
-🐛 Troubleshooting
-Common Issues
-Authentication Not Working
-bash# Check environment variables
+```
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+#### Authentication Not Working
+
+```bash
+# Check environment variables
 docker-compose exec enact-api env | grep -E "(DISABLE_AUTH|KEYCLOAK)"
 
 # Verify Keycloak connectivity
@@ -261,8 +347,12 @@ curl -s "https://your-keycloak.com/realms/your-realm/.well-known/openid_configur
 
 # Check application logs
 docker-compose logs enact-api | grep -i "auth\|error"
-Database Connection Issues
-bash# Test database connectivity
+```
+
+#### Database Connection Issues
+
+```bash
+# Test database connectivity
 docker-compose exec postgres psql -U enact_user -c "SELECT version();"
 
 # Check database logs
@@ -270,8 +360,12 @@ docker-compose logs postgres
 
 # Verify environment variables
 echo $DATABASE_URL
-Container Issues
-bash# Restart specific service
+```
+
+#### Container Issues
+
+```bash
+# Restart specific service
 docker-compose restart enact-api
 
 # Complete restart
@@ -279,8 +373,12 @@ docker-compose down && docker-compose up -d
 
 # Clean restart (removes volumes)
 docker-compose down -v && docker-compose up -d
-SSL/HTTPS Issues
-bash# Test SSL certificate
+```
+
+#### SSL/HTTPS Issues
+
+```bash
+# Test SSL certificate
 openssl x509 -in ssl/fullchain.pem -text -noout
 
 # Check nginx configuration
@@ -288,8 +386,12 @@ docker-compose exec nginx nginx -t
 
 # View nginx error logs
 docker-compose logs nginx
-Performance Tuning
-bash# Monitor container resources
+```
+
+### Performance Tuning
+
+```bash
+# Monitor container resources
 docker stats
 
 # Database performance monitoring
@@ -300,9 +402,14 @@ docker-compose exec postgres psql -U enact_user -c "
 
 # Application metrics endpoint
 curl https://your-domain.com/metrics
-🔄 Updates & Upgrades
-Application Updates
-bash# Pull latest code
+```
+
+## 🔄 Updates & Upgrades
+
+### Application Updates
+
+```bash
+# Pull latest code
 git pull origin main
 
 # Rebuild and restart
@@ -311,8 +418,12 @@ docker-compose up -d enact-api
 
 # Check if migrations are needed
 docker-compose logs enact-api | grep -i "migration\|schema"
-Dependency Updates
-bash# Update Node.js dependencies
+```
+
+### Dependency Updates
+
+```bash
+# Update Node.js dependencies
 cd app
 npm update
 npm audit fix
@@ -320,42 +431,57 @@ npm audit fix
 # Rebuild container
 cd ..
 docker-compose build enact-api
-📚 Additional Resources
+```
+
+## 📚 Additional Resources
 
-Eclipse Dataspace Connector Documentation
-Keycloak Administration Guide
-Docker Compose Reference
-Nginx Configuration Guide
+- [Eclipse Dataspace Connector Documentation](https://eclipse-edc.github.io/Connector/)
+- [Keycloak Administration Guide](https://www.keycloak.org/docs/latest/server_admin/)
+- [Docker Compose Reference](https://docs.docker.com/compose/)
+- [Nginx Configuration Guide](https://nginx.org/en/docs/)
+
+## 🆘 Support
 
-🆘 Support
 For issues and questions:
 
-Check logs: docker-compose logs
-Verify configuration: Environment variables and certificates
-Test connectivity: Database, Keycloak, external services
-Review documentation: This README and component docs
-
-🔒 Security Considerations
-Production Checklist
-
- Strong passwords for all services
- Valid SSL certificates with proper chain
- Firewall rules restricting access
- Regular backups automated
- Log monitoring configured
- Security headers enabled in Nginx
- API rate limiting configured
- Database access restricted
- Secrets management (consider using Docker secrets)
- Regular security updates for all components
-
-Security Headers
+1. **Check logs**: `docker-compose logs`
+2. **Verify configuration**: Environment variables and certificates
+3. **Test connectivity**: Database, Keycloak, external services
+4. **Review documentation**: This README and component docs
+
+## 🔒 Security Considerations
+
+### Production Checklist
+
+- [ ] Strong passwords for all services
+- [ ] Valid SSL certificates with proper chain
+- [ ] Firewall rules restricting access
+- [ ] Regular backups automated
+- [ ] Log monitoring configured
+- [ ] Security headers enabled in Nginx
+- [ ] API rate limiting configured
+- [ ] Database access restricted
+- [ ] Secrets management (consider using Docker secrets)
+- [ ] Regular security updates for all components
+
+### Security Headers
+
 The nginx configuration includes:
 
-Strict-Transport-Security
-X-Frame-Options
-X-Content-Type-Options
-X-XSS-Protection
-Referrer-Policy
+- `Strict-Transport-Security`
+- `X-Frame-Options`
+- `X-Content-Type-Options`
+- `X-XSS-Protection`
+- `Referrer-Policy`
+
+Customize these in `nginx/nginx.conf` as needed for your security requirements.
+
+---
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+
+## License
 
-Customize these in nginx/nginx.conf as needed for your security requirements.
+This project is licensed under the Eclipse Public License 2.0 - see the [LICENSE](LICENSE) file for details.
\ No newline at end of file