Deploying KeystoneJS

Introduction

KeystoneJS is a superpowered headless CMS and application framework for Node.js, built with GraphQL and React. It auto-generates a powerful GraphQL API and a beautiful, customizable Admin UI from your data schema, letting you focus on building your application rather than boilerplate code.

As a true application framework (not just a CMS), Keystone gives developers full control over their data model, business logic, and API design. The schema-driven approach means you define your content types in code, getting type-safety, version control, and the flexibility to extend functionality as needed.

Key highlights of KeystoneJS:

• GraphQL API: Auto-generated, fully-featured GraphQL API with filtering, pagination, and relationships
• Admin UI: Beautiful, customizable React-based admin interface out of the box
• Schema-Driven: Define your data model in TypeScript with full type safety
• Flexible Access Control: Fine-grained permissions at the field and operation level
• Document Fields: Rich text editing with customizable block types
• Image and File Management: Built-in handling for uploads and cloud storage
• Authentication: Session management with multiple auth strategies
• Database Support: Works with PostgreSQL, MySQL, SQLite, and MongoDB
• Hooks and Extensions: Lifecycle hooks for custom business logic
• TypeScript First: Full TypeScript support throughout

This guide walks through deploying a KeystoneJS application on Klutch.sh using Docker, configuring database connections, and preparing your project for production.

Why Deploy KeystoneJS on Klutch.sh

Deploying KeystoneJS on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds your Keystone app without complex configuration. Push to GitHub, and your CMS deploys automatically.

Persistent Storage: Attach persistent volumes for file uploads and database storage if using SQLite.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, essential for secure API access and admin panel.

GitHub Integration: Connect your repository directly for continuous deployment. Schema changes trigger automatic rebuilds.

Environment Variable Management: Securely store database credentials and session secrets through Klutch.sh’s environment variable system.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Keystone project
• A KeystoneJS project (or follow along to create one)
• Basic familiarity with Node.js and Docker
• A PostgreSQL database (recommended for production)

Preparing Your Repository

Creating a KeystoneJS Project

If you don’t have a Keystone project yet:

npm create keystone-app@latest my-keystone-app
cd my-keystone-app

Repository Structure

Your Keystone project with Docker support:

my-keystone-app/
├── Dockerfile
├── .dockerignore
├── keystone.ts
├── schema.ts
├── package.json
└── ...

Creating the Dockerfile

Create a Dockerfile in your project root:

FROM node:20-alpine AS builder

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm ci

# Copy source files
COPY . .

# Build the Keystone application
RUN npm run build

# Production image
FROM node:20-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production

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

# Create uploads directory
RUN mkdir -p /app/public/uploads

EXPOSE 3000

CMD ["npm", "start"]

Environment Variables Reference

Variable	Required	Description
DATABASE_URL	Yes	PostgreSQL connection string
SESSION_SECRET	Yes	Secret for session encryption (min 32 chars)
NODE_ENV	No	Set to production for production builds
ASSET_BASE_URL	No	Base URL for uploaded assets

Updating keystone.ts for Production

Ensure your keystone.ts is production-ready:

import { config } from '@keystone-6/core';
import { lists } from './schema';

export default config({
  db: {
    provider: 'postgresql',
    url: process.env.DATABASE_URL!,
  },
  lists,
  session: {
    secret: process.env.SESSION_SECRET!,
  },
  server: {
    port: 3000,
  },
});

Creating the .dockerignore File

node_modules
.git
.github
*.md
.env
.env.local
.keystone
dist

Deploying KeystoneJS on Klutch.sh

Set Up PostgreSQL Database

KeystoneJS works best with PostgreSQL in production:

• Use a managed PostgreSQL service
• Deploy PostgreSQL on Klutch.sh
• Use a cloud database provider

Note your connection URL: postgresql://user:password@host:5432/keystone

Generate Session Secret

openssl rand -base64 32

Save this for environment variables configuration.

Push Your Repository to GitHub

git add Dockerfile .dockerignore
git commit -m "Add Docker configuration for Klutch.sh deployment"
git push origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project.

Create a New App

Within your project, create a new app. Connect your GitHub account and select your Keystone repository.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Variable	Value
DATABASE_URL	Your PostgreSQL connection string
SESSION_SECRET	Your generated session secret
NODE_ENV	production

Attach Persistent Volumes (Optional)

If handling file uploads locally:

Mount Path	Recommended Size	Purpose
/app/public/uploads	5 GB	Uploaded files and images

Deploy Your Application

Click Deploy to build and launch your Keystone application.

Access KeystoneJS

Once deployment completes, access your Keystone instance:

• Admin UI: https://your-app-name.klutch.sh/
• GraphQL Playground: https://your-app-name.klutch.sh/api/graphql

Initial Setup

Creating Your First User

On first access to the Admin UI:

1. You’ll be prompted to create an admin user
2. Enter email and password
3. Log in to access the dashboard

Exploring the Admin UI

The auto-generated Admin UI provides:

• Content Management: Create and edit content based on your schema
• User Management: Manage admin users and permissions
• Relationship Navigation: Easy linking between related items

Using the GraphQL API

Access the GraphQL Playground to:

• Explore your auto-generated schema
• Test queries and mutations
• View documentation for all types and fields

Example query:

query {
  posts {
    id
    title
    content
    author {
      name
    }
  }
}

Production Best Practices

Database Management

• Migrations: Use Keystone’s migration system for schema changes
• Backups: Regularly backup your PostgreSQL database
• Connection Pooling: Configure for high-traffic applications

File Storage

For production file handling, consider:

• Cloud Storage: Use S3, Cloudinary, or similar services
• CDN: Serve static assets through a CDN
• Local Storage: Ensure persistent volumes are properly sized

Security Recommendations

• Strong Session Secret: Use a cryptographically secure secret
• Access Control: Implement proper field-level permissions
• Keep Updated: Regularly update Keystone and dependencies

Troubleshooting Common Issues

Database Connection Errors

Solutions:

• Verify DATABASE_URL format and credentials
• Check database is accessible from Klutch.sh
• Ensure database exists and user has proper permissions

Build Failures

Solutions:

• Check for TypeScript errors in your schema
• Verify all dependencies are properly declared
• Review build logs for specific error messages

Admin UI Not Loading

Solutions:

• Verify the build completed successfully
• Check SESSION_SECRET is properly set
• Clear browser cache and cookies

Additional Resources

• KeystoneJS Website
• KeystoneJS Documentation
• KeystoneJS GitHub Repository
• Deployment Guide
• Klutch.sh Deployments

Conclusion

Deploying KeystoneJS on Klutch.sh gives you a powerful headless CMS and application framework with automatic builds, persistent storage, and secure HTTPS access. The combination of Keystone’s developer-friendly approach and Klutch.sh’s deployment simplicity means you can focus on building your application rather than infrastructure.

With its auto-generated GraphQL API, customizable Admin UI, and flexible schema system, KeystoneJS on Klutch.sh provides the foundation for content-rich applications that scale with your needs.