Deploying Graphweaver

Introduction

Graphweaver is a data integration platform that transforms your data sources into a unified GraphQL API. By connecting databases, SaaS platforms, and REST APIs, Graphweaver automatically generates a fully-featured GraphQL API with CRUD operations, filtering, pagination, and granular permissions.

Built for developers who need to rapidly build APIs without writing boilerplate code, Graphweaver introspects your data sources and generates TypeScript code that can be customized and extended. The platform supports row-level and column-level security, making it suitable for multi-tenant applications.

Key highlights of Graphweaver:

Instant GraphQL API: Auto-generate CRUD operations from any data source
Multiple Data Sources: Connect Postgres, MySQL, SQLite, REST APIs, and SaaS platforms
Granular Permissions: Row-level and column-level security controls
Type Safety: Full TypeScript support with generated types
Schema Introspection: Automatically discover database schema
Customizable: Extend and modify any generated operation
Admin UI: Built-in admin interface for data exploration
Real-Time: Subscription support for live data updates
Federation Ready: Compose multiple GraphQL services
100% Open Source: Licensed under MIT

This guide walks through deploying Graphweaver on Klutch.sh using Docker, connecting your data sources, and building your GraphQL API.

Why Deploy Graphweaver on Klutch.sh

Deploying Graphweaver on Klutch.sh provides several advantages for API development:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Graphweaver without complex orchestration. Push to GitHub and your GraphQL API deploys automatically.

Database Integration: Connect to databases deployed on Klutch.sh or external data sources.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure API access.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Scalable Resources: Allocate CPU and memory based on API traffic and data volume.

Custom Domains: Assign a custom domain for your GraphQL endpoint.

Always-On Availability: Your API remains accessible 24/7.

Prerequisites

Before deploying Graphweaver on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your Graphweaver project
A database to connect (PostgreSQL, MySQL, or SQLite)
Basic familiarity with Docker, Node.js, and GraphQL concepts
Node.js installed locally for initial project setup

Understanding Graphweaver Architecture

Graphweaver consists of several components:

CLI Tool: Scaffolds projects and introspects data sources.

Backend Package: Core GraphQL server with resolvers and middleware.

Data Connectors: Adapters for different data sources (PostgreSQL, MySQL, REST, etc.).

Admin UI: Web interface for exploring and managing data.

Generated Code: TypeScript entities and resolvers based on your schema.

Creating a Graphweaver Project

Before deployment, create and configure your Graphweaver project locally.

Initialize the Project

Create a new Graphweaver project:

npx graphweaver@latest init my-graphweaver-api
cd my-graphweaver-api

Connect to PostgreSQL

Add the PostgreSQL backend:

npm install @exogee/graphweaver-postgres

Introspect Your Database

Generate entities from your existing database:

npx graphweaver import postgres \
  --host localhost \
  --port 5432 \
  --database mydb \
  --user myuser \
  --password mypassword

This creates TypeScript entity files based on your database schema.

Project Structure

After initialization, your project looks like:

my-graphweaver-api/
├── src/
│   ├── backend/
│   │   ├── entities/
│   │   │   ├── user.ts
│   │   │   └── post.ts
│   │   └── index.ts
│   └── admin-ui/
├── package.json
├── Dockerfile
└── .env

Preparing for Deployment

Creating the Dockerfile

Create or update the Dockerfile:

FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci

# Copy source code
COPY . .

# Build the application
RUN npm run build

# Production stage
FROM node:20-alpine

WORKDIR /app

# Copy built application
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

# Set environment variables
ENV NODE_ENV=production
ENV PORT=9001

# Expose the port
EXPOSE 9001

# Start the application
CMD ["node", "dist/backend/index.js"]

Creating the .dockerignore File

Create a .dockerignore file:

node_modules
.git
.github
*.md
README.md
.env.local
.DS_Store
dist

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_URL`	Yes	-	PostgreSQL connection string
`PORT`	No	9001	Port to listen on
`NODE_ENV`	No	production	Node environment
`AUTH_SECRET`	No	-	Secret for JWT authentication
`ADMIN_UI_ENABLED`	No	true	Enable admin interface

Deploying Graphweaver on Klutch.sh

Once your project is ready, follow these steps to deploy:

Push Your Repository to GitHub

Push your Graphweaver project to GitHub:

git init
git add .
git commit -m "Initial Graphweaver project"
git remote add origin https://github.com/yourusername/my-graphweaver-api.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “graphweaver-api”.

Deploy a PostgreSQL Database

If you don’t have a database, deploy one on Klutch.sh. See the PostgreSQL deployment guide.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select your Graphweaver repository.

Configure HTTP Traffic

Graphweaver serves its GraphQL API over HTTP. In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 9001

Set Environment Variables

In the environment variables section, add:

Variable	Value
`DATABASE_URL`	`postgresql://user:password@host:port/database`
`PORT`	`9001`
`NODE_ENV`	`production`

Replace the database URL with your actual PostgreSQL connection string.

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

Detect your Dockerfile automatically
Build the container image
Start the Graphweaver container
Provision an HTTPS certificate

Access Your GraphQL API

Once deployment completes, access your GraphQL API at:

GraphQL Endpoint: https://your-app-name.klutch.sh/graphql
Admin UI: https://your-app-name.klutch.sh

Using the GraphQL API

GraphQL Playground

Access the GraphQL playground to explore your API:

Navigate to https://your-app-name.klutch.sh/graphql
Write and execute queries
Explore the schema documentation

Example Queries

Fetch all users:

query {
  users {
    id
    name
    email
    posts {
      title
    }
  }
}

Create a new user:

mutation {
  createUser(input: {
    name: "John Doe"
    email: "john@example.com"
  }) {
    id
    name
  }
}

Filter and paginate:

query {
  users(
    filter: { name: { contains: "John" } }
    pagination: { limit: 10, offset: 0 }
  ) {
    id
    name
  }
}

Customizing Your API

Adding Custom Resolvers

Extend generated entities with custom logic:

import { Entity, Field, ID, Resolver, Query } from '@exogee/graphweaver';

@Entity('User', { provider: new PostgresBackendProvider() })
export class User {
  @Field(() => ID)
  id!: string;

  @Field(() => String)
  name!: string;

  @Field(() => String)
  email!: string;
}

@Resolver(() => User)
export class UserResolver {
  @Query(() => User)
  async currentUser(@Context() ctx: any): Promise<User | null> {
    return ctx.user;
  }
}

Adding Permissions

Implement row-level security:

import { AccessControlList, ApplyAccessControlList } from '@exogee/graphweaver';

const userAcl: AccessControlList<User> = {
  CRUD: {
    read: (ctx) => ({
      organizationId: ctx.user.organizationId
    }),
    write: (ctx) => ({
      organizationId: ctx.user.organizationId
    })
  }
};

@ApplyAccessControlList(userAcl)
@Entity('User', { provider: new PostgresBackendProvider() })
export class User {
  // ...
}

Connecting Multiple Data Sources

Add additional backends:

// MySQL
import { MySqlBackendProvider } from '@exogee/graphweaver-mysql';

// REST API
import { RestBackendProvider } from '@exogee/graphweaver-rest';

// Combine in your entities
@Entity('ExternalUser', { provider: new RestBackendProvider({
  baseUrl: 'https://api.example.com'
}) })
export class ExternalUser {
  // ...
}

Admin UI

Accessing the Admin Interface

Navigate to your Graphweaver URL to access the admin UI:

View and search all entities
Create, update, and delete records
Explore relationships between entities
Run custom queries

Customizing the Admin UI

Configure the admin interface in your entities:

@Entity('User', {
  provider: new PostgresBackendProvider(),
  adminUIOptions: {
    defaultFilter: { active: true },
    defaultSort: { field: 'createdAt', direction: 'DESC' }
  }
})
export class User {
  // ...
}

Security Best Practices

Authentication

Implement authentication middleware:

import { AuthenticationBaseEntity } from '@exogee/graphweaver-auth';

export class Authentication extends AuthenticationBaseEntity {
  async authenticate(username: string, password: string) {
    // Implement your authentication logic
  }
}

Environment Variables

Store secrets in Klutch.sh environment variables
Never commit credentials to your repository
Use different credentials for development and production

Access Control

Define ACLs for all entities
Implement row-level security for multi-tenant apps
Use column-level permissions for sensitive data

Troubleshooting Common Issues

Database Connection Errors

Symptoms: Cannot connect to PostgreSQL.

Solutions:

Verify DATABASE_URL is correct
Check database is accessible from Klutch.sh
Verify database user has required permissions
Check for SSL requirements

Build Failures

Symptoms: Docker build fails.

Solutions:

Check TypeScript compilation errors locally
Verify all dependencies are in package.json
Check for missing environment variables
Review build logs for specific errors

API Returns Empty Results

Symptoms: Queries return no data.

Solutions:

Verify database has data
Check ACL permissions aren’t too restrictive
Review GraphQL query syntax
Check for filter conditions

Additional Resources

Conclusion

Deploying Graphweaver on Klutch.sh gives you a powerful, auto-generated GraphQL API with minimal boilerplate. The combination of Graphweaver’s schema introspection and Klutch.sh’s deployment simplicity means you can build production APIs in minutes rather than days.

With support for multiple data sources, granular permissions, and a built-in admin UI, Graphweaver provides everything you need for modern API development. Whether you’re building internal tools, customer-facing APIs, or connecting disparate data sources, Graphweaver on Klutch.sh delivers a flexible, type-safe GraphQL API on your terms.