Deploying Manifest

Introduction

Manifest is a self-hosted backend-as-a-service (BaaS) platform that lets you create powerful backends with a visual interface. It provides instant REST and GraphQL APIs for your data models, authentication, file storage, and more, allowing you to build applications without writing server-side code.

Built for developers who want the convenience of services like Firebase or Supabase while maintaining complete control over their data, Manifest offers a compelling self-hosted alternative. Define your data models visually, and Manifest generates type-safe APIs automatically.

Key highlights of Manifest:

• Visual Data Modeling: Design your database schema with a visual interface
• Instant REST APIs: Automatically generated CRUD APIs for all your models
• GraphQL Support: Optional GraphQL endpoint for flexible queries
• Authentication: Built-in user authentication and authorization
• File Storage: Managed file uploads and storage
• Webhooks: Trigger external services on data changes
• Admin Panel: Built-in admin interface for data management
• TypeScript SDK: Type-safe client library for frontend integration
• Role-Based Access: Fine-grained permissions system
• Real-Time Subscriptions: Live data updates via WebSockets
• Self-Hosted: Complete control over your data and infrastructure
• Open Source: MIT licensed with active development

This guide walks through deploying Manifest on Klutch.sh using Docker, setting up your first backend, and connecting frontend applications.

Why Deploy Manifest on Klutch.sh

Deploying Manifest on Klutch.sh provides several advantages:

Complete Data Ownership: Unlike cloud BaaS providers, your data stays on infrastructure you control.

Predictable Pricing: No per-request charges or surprise bills as your application scales.

HTTPS by Default: Automatic SSL certificates for secure API communication.

Persistent Storage: Your database and files persist across deployments.

GitHub Integration: Update your configuration through Git with automatic redeployments.

Custom Domains: Use your own domain for professional API endpoints.

Scalable Resources: Allocate CPU and memory based on your application’s needs.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Manifest configuration
• Basic familiarity with Docker and API concepts
• (Optional) A frontend application to connect to Manifest

Understanding Manifest Architecture

Manifest is designed as a comprehensive backend platform:

Core Server: The main application handles API requests, authentication, and business logic.

Database: Supports SQLite for simple deployments or PostgreSQL for production workloads.

File Storage: Manages uploaded files with configurable storage backends.

Admin Dashboard: Web interface for managing data models and content.

API Layer: Automatically generated REST and GraphQL endpoints.

Preparing Your Repository

To deploy Manifest on Klutch.sh, create a GitHub repository containing your Dockerfile and schema configuration.

Repository Structure

manifest-deploy/
├── Dockerfile
├── manifest.yml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM mnfst/manifest:latest

# Environment configuration
ENV NODE_ENV=production
ENV PORT=1111

# Database configuration
ENV DATABASE_URL=${DATABASE_URL:-file:/data/manifest.db}

# Secret key for JWT tokens
ENV JWT_SECRET=${JWT_SECRET}

# Create data directories
RUN mkdir -p /data /uploads

# Copy schema configuration
COPY manifest.yml /app/manifest.yml

# Expose the API port
EXPOSE 1111

Creating the Schema Configuration

Create a manifest.yml file to define your data models:

name: My Manifest Backend
entities:
  Post:
    properties:
      - name: title
        type: string
      - name: content
        type: text
      - name: published
        type: boolean
        default: false
      - name: publishedAt
        type: datetime
    belongsTo:
      - Author

  Author:
    properties:
      - name: name
        type: string
      - name: email
        type: email
      - name: bio
        type: text
    hasMany:
      - Post

  Category:
    properties:
      - name: name
        type: string
      - name: slug
        type: string
    hasMany:
      - Post

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
README.md
LICENSE
.gitignore
*.log
.DS_Store
.env
node_modules/

Environment Variables Reference

Variable	Required	Default	Description
DATABASE_URL	Yes	-	Database connection string
JWT_SECRET	Yes	-	Secret key for JWT token signing
PORT	No	1111	Port for the API server
NODE_ENV	No	production	Environment mode

Deploying Manifest on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Generate a JWT Secret

Generate a secure secret key for JWT tokens:

openssl rand -hex 64

Save this key securely for the environment variables configuration.

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile manifest.yml .dockerignore
git commit -m "Initial Manifest deployment configuration"
git remote add origin https://github.com/yourusername/manifest-deploy.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 “manifest” or “backend-api”.

Create a New App

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

Configure HTTP Traffic

Manifest serves its API over HTTP. In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 1111 (Manifest’s default port)

Set Environment Variables

In the environment variables section, add:

Variable	Value
JWT_SECRET	Your generated secret key
DATABASE_URL	file:/data/manifest.db (for SQLite) or PostgreSQL connection string

Attach Persistent Volumes

Persistent storage is essential for your backend. Add volumes:

Mount Path	Recommended Size	Purpose
/data	10 GB	Database storage
/uploads	20 GB	File uploads

Deploy Your Application

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

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Manifest container
• Provision an HTTPS certificate

Access Manifest

Once deployment completes, access your Manifest admin panel at https://your-app-name.klutch.sh/admin.

Initial Setup and Configuration

Accessing the Admin Panel

Navigate to https://your-app-name.klutch.sh/admin to access the Manifest admin interface. Here you can:

• View and edit your data models
• Manage content
• Configure authentication settings
• Monitor API usage

Understanding Your API

Manifest automatically generates API endpoints for your entities:

REST Endpoints:

GET    /api/posts         # List all posts
GET    /api/posts/:id     # Get single post
POST   /api/posts         # Create post
PUT    /api/posts/:id     # Update post
DELETE /api/posts/:id     # Delete post

Filtering and Pagination:

GET /api/posts?published=true              # Filter by field
GET /api/posts?_page=1&_limit=10           # Pagination
GET /api/posts?_sort=publishedAt&_order=desc  # Sorting

Defining Data Models

Entity Configuration

Define entities in your manifest.yml:

entities:
  Product:
    properties:
      - name: name
        type: string
        required: true
      - name: description
        type: text
      - name: price
        type: number
      - name: sku
        type: string
        unique: true
      - name: inStock
        type: boolean
        default: true
      - name: image
        type: image

Property Types

Type	Description
string	Short text
text	Long text
number	Numeric values
boolean	True/false
datetime	Date and time
email	Email addresses
image	Image upload
file	File upload

Relationships

Define relationships between entities:

entities:
  Order:
    properties:
      - name: orderNumber
        type: string
      - name: total
        type: number
    belongsTo:
      - Customer
    hasMany:
      - OrderItem

  Customer:
    properties:
      - name: name
        type: string
      - name: email
        type: email
    hasMany:
      - Order

  OrderItem:
    properties:
      - name: quantity
        type: number
      - name: price
        type: number
    belongsTo:
      - Order
      - Product

Authentication and Authorization

Enabling Authentication

Add authentication to your manifest.yml:

auth:
  enabled: true
  entity: User
  identityField: email
  credentialField: password

entities:
  User:
    properties:
      - name: email
        type: email
        unique: true
      - name: password
        type: password
      - name: name
        type: string
      - name: role
        type: string
        default: user

Authentication Endpoints

When authentication is enabled:

POST /api/auth/signup    # Create new user
POST /api/auth/login     # Authenticate and get token
GET  /api/auth/me        # Get current user

Using Authentication

Include the JWT token in requests:

fetch('https://your-app-name.klutch.sh/api/posts', {
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN'
  }
})

Access Control

Configure entity-level permissions:

entities:
  Post:
    policies:
      create: authenticated
      read: public
      update: owner
      delete: admin

Connecting Frontend Applications

JavaScript/TypeScript

Use the Manifest client SDK:

import { Manifest } from '@manifest/sdk'

const manifest = new Manifest({
  url: 'https://your-app-name.klutch.sh'
})

// Fetch all posts
const posts = await manifest.from('posts').find()

// Create a new post
const newPost = await manifest.from('posts').create({
  title: 'Hello World',
  content: 'My first post',
  published: true
})

// With authentication
await manifest.auth.login('user@example.com', 'password')
const myPosts = await manifest.from('posts').find()

React Example

import { useManifest } from '@manifest/react'

function Posts() {
  const { data: posts, loading, error } = useManifest('posts')

  if (loading) return <div>Loading...</div>
  if (error) return <div>Error: {error.message}</div>

  return (
    <ul>
      {posts.map(post => (
        <li key={post.id}>{post.title}</li>
      ))}
    </ul>
  )
}

Direct API Calls

Use any HTTP client:

# List posts
curl https://your-app-name.klutch.sh/api/posts

# Create post
curl -X POST https://your-app-name.klutch.sh/api/posts \
  -H "Content-Type: application/json" \
  -d '{"title": "New Post", "content": "Content here"}'

Production Best Practices

Security Recommendations

• Secure JWT Secret: Use a long, random secret and never expose it
• Enable Authentication: Protect sensitive endpoints with authentication
• CORS Configuration: Configure allowed origins appropriately
• Input Validation: Manifest validates inputs based on your schema

Database Considerations

SQLite (Default):

• Good for small to medium applications
• Simple backup (single file)
• Limited concurrent write performance

PostgreSQL (Recommended for Production):

• Better performance at scale
• Advanced querying capabilities
• Connection pooling support

Backup Strategy

1. Database Backups: Regular backups of /data volume
2. File Backups: Back up /uploads for user-uploaded files
3. Schema Versioning: Keep manifest.yml in version control

Troubleshooting Common Issues

API Returns 401 Unauthorized

Symptoms: Requests fail with authentication errors.

Solutions:

• Verify JWT token is valid and not expired
• Check Authorization header format
• Ensure the endpoint requires authentication
• Verify JWT_SECRET matches between requests

Database Migration Issues

Symptoms: Schema changes not reflected in API.

Solutions:

• Restart the container after schema changes
• Check logs for migration errors
• Verify manifest.yml syntax is correct
• Back up data before major schema changes

File Uploads Failing

Symptoms: Image or file uploads return errors.

Solutions:

• Verify /uploads volume is mounted
• Check file size limits
• Ensure correct content type headers
• Check available disk space

Slow API Performance

Symptoms: API requests take a long time.

Solutions:

• Add indexes to frequently queried fields
• Use pagination for large datasets
• Consider PostgreSQL for heavy workloads
• Optimize queries with selective field fetching

Additional Resources

• Manifest Documentation
• Manifest GitHub Repository
• Manifest Examples
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Manifest on Klutch.sh gives you a powerful, self-hosted backend-as-a-service platform with complete control over your data. The combination of visual data modeling, instant APIs, and built-in authentication makes it easy to build applications without writing server-side code.

Whether you’re building a blog, e-commerce site, or complex application, Manifest provides the backend infrastructure you need while keeping your data private and your costs predictable. With Klutch.sh’s reliable hosting and automatic HTTPS, your APIs are always available and secure.

Take the convenience of modern BaaS platforms and combine it with the freedom of self-hosting for the best of both worlds.