Skip to content

open-source.mdx

Latest commit

 

History

History
411 lines (320 loc) · 9.86 KB

open-source.mdx

File metadata and controls

411 lines (320 loc) · 9.86 KB
title Open Source
description Deploy and run Fusioncat on your own infrastructure
icon github

Overview

Fusioncat is available as an open-source solution that you can deploy and run on your own infrastructure. This gives you complete control over your data, customization options, and the ability to contribute to the project's development.

The open-source version includes all core features for managing asynchronous messaging architectures.

Why Self-Host Fusioncat?

Your data never leaves your infrastructure. Perfect for organizations with strict compliance requirements. Modify and extend Fusioncat to meet your specific needs. Add custom protocols, templates, or integrations.

Quick Start

Get Fusioncat running in under 5 minutes using Docker.

Prerequisites

Before you begin, ensure you have:

  • Docker installed on your system
  • PostgreSQL 13+ database (or use Docker Compose with included PostgreSQL)

Installation Methods

The fastest way to get started with Fusioncat. 
```bash
# Pull the latest Fusioncat image
docker pull ghcr.io/fusioncatltd/fusioncat:latest

# Run Fusioncat with your PostgreSQL database
docker run -d \
  --name fusioncat \
  -p 8080:8080 \
  -e PG_HOST=your-postgres-host \
  -e PG_PORT=5432 \
  -e PG_USER=your-db-user \
  -e PG_PASSWORD=your-db-password \
  -e PG_DB_NAME=fusioncat \
  -e JWT_SECRET=your-secret-key \
  ghcr.io/fusioncatltd/fusioncat:latest
```

<Note>
  Replace the database credentials with your actual PostgreSQL connection details.
</Note>

Verify the installation:
```bash
curl http://localhost:8080/health
```

You should see:
```json
{
  "status": "healthy",
  "service": "fusioncat"
}
```
For a complete setup including PostgreSQL, use Docker Compose. 
Create a file named `docker-compose.yml`:

```yaml
version: '3.8'

services:
  fusioncat:
    image: ghcr.io/fusioncatltd/fusioncat:latest
    ports:
      - "8080:8080"
    environment:
      PG_HOST: postgres
      PG_PORT: 5432
      PG_USER: fusioncat
      PG_PASSWORD: ${DB_PASSWORD}
      PG_DB_NAME: fusioncat
      JWT_SECRET: ${JWT_SECRET}
    depends_on:
      - postgres
    restart: unless-stopped

  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_USER: fusioncat
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: fusioncat
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  postgres_data:
```

Create an `.env` file with your secrets:
```bash
DB_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret-key
```

Start the services:
```bash
docker-compose up -d
```

<Check>
  Both Fusioncat and PostgreSQL will start automatically and restart if they crash.
</Check>
For development or customization, build Fusioncat from source. 
**Prerequisites:**
- Go 1.23+
- Node.js 18+ (for quicktype)
- PostgreSQL 13+
- Make

Clone and build:
```bash
# Clone the repository
git clone https://github.com/fusioncatltd/fusioncat.git
cd fusioncat

# Copy and configure environment
cp .env.template .env
# Edit .env with your database credentials

# Install dependencies
go mod download
npm install -g quicktype

# Run locally
make run

# Or build Docker image
make docker-build
```

For development with hot reload:
```bash
go install github.com/cosmtrek/air@latest
air
```

Configuration

Fusioncat is configured through environment variables. Here are the key settings:

Variable Description Default Required
PG_HOST PostgreSQL host address localhost ✅
PG_PORT PostgreSQL port 5432 ✅
PG_USER Database username - ✅
PG_PASSWORD Database password - ✅
PG_DB_NAME Database name fusioncat ✅
PG_SSLMODE PostgreSQL SSL mode require ❌
JWT_SECRET Secret for JWT tokens - ✅
ADMIN_URL Admin panel URL http://localhost:3000 ❌
Always use strong, unique values for `JWT_SECRET` and `PG_PASSWORD` in production.

First Steps After Installation

Once Fusioncat is running, you can start using it immediately:

1. Create Your First User

curl -X POST http://localhost:8080/v1/public/users \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "SecurePassword123!"
  }'

2. Authenticate

curl -X POST http://localhost:8080/v1/public/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@example.com",
    "password": "SecurePassword123!"
  }'

Save the returned JWT token for authenticated requests.

3. Create Your First Project

curl -X POST http://localhost:8080/v1/protected/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Messaging System",
    "description": "Production messaging architecture"
  }'

4. Access the API Documentation

Open your browser and navigate to:

http://localhost:8080/swagger/index.html

This provides interactive API documentation for all available endpoints.

Architecture Overview

Understanding Fusioncat's architecture helps you deploy and scale it effectively.

graph TB
    subgraph "Your Infrastructure"
        FC[Fusioncat API Server]
        PG[(PostgreSQL Database)]
        
        subgraph "Your Services"
            S1[Service A]
            S2[Service B]
            S3[Service C]
        end
        
        subgraph "Message Brokers"
            K[Kafka]
            R[RabbitMQ]
            M[MQTT]
        end
    end
    
    FC --> PG
    FC -.->|Generates Code| S1
    FC -.->|Generates Code| S2
    FC -.->|Generates Code| S3
    
    S1 <--> K
    S2 <--> R
    S3 <--> M
Loading

Key Components

  • API Server: RESTful API for managing projects, schemas, and code generation
  • PostgreSQL: Stores all configuration, schemas, and project metadata

Security Considerations

When self-hosting Fusioncat, consider these security best practices:

Deploy Fusioncat behind a reverse proxy (nginx, Traefik) with SSL/TLS certificates. - Use strong passwords - Enable SSL for database connections - Restrict network access to PostgreSQL Deploy in a private network segment, accessible only to authorized services. Keep Fusioncat updated to the latest version for security patches. ```bash docker pull ghcr.io/fusioncatltd/fusioncat:latest ``` Regularly backup your PostgreSQL database containing all your schemas and configurations.

Monitoring & Observability

Monitor your Fusioncat deployment for optimal performance:

Health Checks

The /health endpoint provides basic health status:

curl http://localhost:8080/health

Logging

Fusioncat logs to stdout/stderr, compatible with any log aggregation system:

docker logs fusioncat

Upgrading Fusioncat

To upgrade to a new version:

```bash # Pull the latest image docker pull ghcr.io/fusioncatltd/fusioncat:latest 
# Stop the current container
docker stop fusioncat
docker rm fusioncat

# Start with the new version
docker run -d \
  --name fusioncat \
  -p 8080:8080 \
  [...your environment variables...] \
  ghcr.io/fusioncatltd/fusioncat:latest
```
```bash # Pull the latest image docker-compose pull 
# Restart services
docker-compose up -d
```
```bash # Update the deployment kubectl set image deployment/fusioncat \ fusioncat=ghcr.io/fusioncatltd/fusioncat:latest 
# Watch the rollout
kubectl rollout status deployment/fusioncat
```
Database migrations are handled automatically on startup. Always backup your database before major upgrades.

Contributing

Fusioncat is open source and welcomes contributions!

Get Involved

Development Setup

# Fork and clone
git clone https://github.com/YOUR-USERNAME/fusioncat.git
cd fusioncat

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
make test

# Submit pull request

Support

Comprehensive guides and API reference Report bugs and request features

License

Fusioncat is licensed under the Apache 2 License, giving you freedom to use, modify, and distribute it in your projects.

Ready to get started? Install Fusioncat now or explore our API documentation to learn more.