> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fusioncat.dev/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Info>
  The open-source version includes all core features for managing asynchronous messaging architectures.
</Info>

## Why Self-Host Fusioncat?

<CardGroup cols={2}>
  <Card title="Complete Data Control" icon="shield-halved">
    Your data never leaves your infrastructure. Perfect for organizations with strict compliance requirements.
  </Card>

  <Card title="Customization Freedom" icon="code">
    Modify and extend Fusioncat to meet your specific needs. Add custom protocols, templates, or integrations.
  </Card>
</CardGroup>

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

<Tabs>
  <Tab title="Docker (Recommended)">
    The fastest way to get started with Fusioncat.

    ```bash theme={null}
    # 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 theme={null}
    curl http://localhost:8080/health
    ```

    You should see:

    ```json theme={null}
    {
      "status": "healthy",
      "service": "fusioncat"
    }
    ```
  </Tab>

  <Tab title="Docker Compose">
    For a complete setup including PostgreSQL, use Docker Compose.

    Create a file named `docker-compose.yml`:

    ```yaml theme={null}
    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 theme={null}
    DB_PASSWORD=your-secure-password
    JWT_SECRET=your-jwt-secret-key
    ```

    Start the services:

    ```bash theme={null}
    docker-compose up -d
    ```

    <Check>
      Both Fusioncat and PostgreSQL will start automatically and restart if they crash.
    </Check>
  </Tab>

  <Tab title="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:

    ```bash theme={null}
    # 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 theme={null}
    go install github.com/cosmtrek/air@latest
    air
    ```
  </Tab>
</Tabs>

## 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](http://localhost:3000) | ❌        |

<Warning>
  Always use strong, unique values for `JWT_SECRET` and `PG_PASSWORD` in production.
</Warning>

## First Steps After Installation

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

### 1. Create Your First User

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

### 2. Authenticate

```bash theme={null}
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

```bash theme={null}
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.

```mermaid theme={null}
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
```

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

<Steps>
  <Step title="Use HTTPS">
    Deploy Fusioncat behind a reverse proxy (nginx, Traefik) with SSL/TLS certificates.
  </Step>

  <Step title="Secure Database">
    * Use strong passwords
    * Enable SSL for database connections
    * Restrict network access to PostgreSQL
  </Step>

  <Step title="Network Isolation">
    Deploy in a private network segment, accessible only to authorized services.
  </Step>

  <Step title="Regular Updates">
    Keep Fusioncat updated to the latest version for security patches.

    ```bash theme={null}
    docker pull ghcr.io/fusioncatltd/fusioncat:latest
    ```
  </Step>

  <Step title="Backup Strategy">
    Regularly backup your PostgreSQL database containing all your schemas and configurations.
  </Step>
</Steps>

## Monitoring & Observability

Monitor your Fusioncat deployment for optimal performance:

### Health Checks

The `/health` endpoint provides basic health status:

```bash theme={null}
curl http://localhost:8080/health
```

### Logging

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

```bash theme={null}
docker logs fusioncat
```

## Upgrading Fusioncat

To upgrade to a new version:

<Tabs>
  <Tab title="Docker">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Docker Compose">
    ```bash theme={null}
    # Pull the latest image
    docker-compose pull

    # Restart services
    docker-compose up -d
    ```
  </Tab>

  <Tab title="Kubernetes">
    ```bash theme={null}
    # Update the deployment
    kubectl set image deployment/fusioncat \
      fusioncat=ghcr.io/fusioncatltd/fusioncat:latest

    # Watch the rollout
    kubectl rollout status deployment/fusioncat
    ```
  </Tab>
</Tabs>

<Note>
  Database migrations are handled automatically on startup. Always backup your database before major upgrades.
</Note>

## Contributing

Fusioncat is open source and welcomes contributions!

### Get Involved

* **GitHub Repository**: [github.com/fusioncatltd/fusioncat](https://github.com/fusioncatltd/fusioncat)
* **Report Issues**: [GitHub Issues](https://github.com/fusioncatltd/fusioncat/issues)
* **Submit Pull Requests**: Fork, improve, and contribute back

### Development Setup

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Documentation" icon="book" href="https://fusioncat.dev/docs">
    Comprehensive guides and API reference
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/fusioncatltd/fusioncat/issues">
    Report bugs and request features
  </Card>
</CardGroup>

## 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](#quick-start) now or explore our [API documentation](/api-reference/introduction) to learn more.