Open Source

Deploy and run Fusioncat on your own infrastructure

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?

Complete Data Control

Your data never leaves your infrastructure. Perfect for organizations with strict compliance requirements.

Customization Freedom

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

Docker (Recommended)

The fastest way to get started with Fusioncat.

# 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

Replace the database credentials with your actual PostgreSQL connection details.

Verify the installation:

curl http://localhost:8080/health

You should see:

{
  "status": "healthy",
  "service": "fusioncat"
}

Docker Compose

For a complete setup including PostgreSQL, use Docker Compose.

Create a file named docker-compose.yml:

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:

DB_PASSWORD=your-secure-password
JWT_SECRET=your-jwt-secret-key

Start the services:

docker-compose up -d

Both Fusioncat and PostgreSQL will start automatically and restart if they crash.

Build from Source

For development or customization, build Fusioncat from source.

Prerequisites:

• Go 1.23+
• Node.js 18+ (for quicktype)
• PostgreSQL 13+
• Make

Clone and build:

# 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:

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": "[e-mail]",
    "password": "SecurePassword123!"
  }'

2. Authenticate

curl -X POST http://localhost:8080/v1/public/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[e-mail]",
    "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.

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:

1. Use HTTPS

   Deploy Fusioncat behind a reverse proxy (nginx, Traefik) with SSL/TLS certificates.

2. Secure Database

   • Use strong passwords
   • Enable SSL for database connections
   • Restrict network access to PostgreSQL
3. Network Isolation

   Deploy in a private network segment, accessible only to authorized services.

4. Regular Updates

   Keep Fusioncat updated to the latest version for security patches.

   docker pull ghcr.io/fusioncatltd/fusioncat:latest
   
5. Backup Strategy

   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:

Docker

# 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

Docker Compose

# Pull the latest image
docker-compose pull

# Restart services
docker-compose up -d

Kubernetes

# 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

• GitHub Repository: github.com/fusioncatltd/fusioncat
• Report Issues: GitHub Issues
• Submit Pull Requests: Fork, improve, and contribute back

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

Documentation

Comprehensive guides and API reference

GitHub Issues

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.