Deploying Strapi

Introduction

Strapi is the leading open-source headless CMS that gives developers the freedom to use their favorite tools and frameworks while giving content editors a friendly interface for managing content. Built with Node.js, Strapi is highly customizable and self-hosted, making it perfect for projects of any size.

With its powerful plugin system, auto-generated API (REST and GraphQL), and intuitive admin panel, Strapi enables teams to build content-rich applications quickly without sacrificing flexibility.

Key highlights of Strapi:

• Headless Architecture: API-first design for any frontend
• REST and GraphQL: Auto-generated APIs for your content
• Admin Panel: Beautiful, customizable content management interface
• Content Types Builder: Create content structures without code
• Media Library: Built-in asset management
• Role-Based Access: Granular permissions for users and API
• Plugin System: Extend functionality with official and community plugins
• Webhooks: Trigger external services on content changes
• i18n Support: Multi-language content management
• Draft System: Draft and publish workflow
• TypeScript Support: Full TypeScript support
• Open Source: MIT licensed with commercial options

This guide walks through deploying Strapi on Klutch.sh using Docker for a production-ready headless CMS.

Why Deploy Strapi on Klutch.sh

Deploying Strapi on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the Node.js application deployment automatically.

Persistent Storage: Content, uploads, and database persist across deployments.

HTTPS by Default: Secure admin and API access with automatic SSL.

GitHub Integration: Version control your Strapi project and deploy updates automatically.

Scalable Resources: Allocate resources based on content volume and API traffic.

Environment Variable Management: Securely store database credentials and API keys.

Custom Domains: Use your brand’s domain for your CMS and API.

High Availability: Keep your content API running 24/7.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your Strapi project
• PostgreSQL database (can be deployed on Klutch.sh or external)
• Basic familiarity with Node.js and Docker
• (Optional) A custom domain for your Strapi instance

Deploying Strapi on Klutch.sh

Create a Strapi Project

If you don’t have an existing Strapi project:

npx create-strapi-app@latest my-project

Or clone your existing Strapi project repository.

Create Your Dockerfile

Create a Dockerfile in your Strapi project root:

FROM node:18-alpine

# Install dependencies for native modules
RUN apk add --no-cache build-base gcc autoconf automake zlib-dev libpng-dev vips-dev

WORKDIR /app

# Copy package files
COPY package*.json ./
COPY yarn.lock* ./

# Install dependencies
RUN npm ci --only=production

# Copy application code
COPY . .

# Build Strapi admin
RUN npm run build

# Set environment variables
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=1337

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

EXPOSE 1337

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:1337/_health || exit 1

CMD ["npm", "start"]

Configure Database for Production

Update config/database.js:

module.exports = ({ env }) => ({
  connection: {
    client: 'postgres',
    connection: {
      host: env('DATABASE_HOST', 'localhost'),
      port: env.int('DATABASE_PORT', 5432),
      database: env('DATABASE_NAME', 'strapi'),
      user: env('DATABASE_USERNAME', 'strapi'),
      password: env('DATABASE_PASSWORD', ''),
      ssl: env.bool('DATABASE_SSL', false),
    },
    debug: false,
  },
});

Configure Server Settings

Update config/server.js:

module.exports = ({ env }) => ({
  host: env('HOST', '0.0.0.0'),
  port: env.int('PORT', 1337),
  url: env('PUBLIC_URL', 'http://localhost:1337'),
  app: {
    keys: env.array('APP_KEYS'),
  },
});

Push Your Repository to GitHub

Commit and push your Strapi project with the Dockerfile.

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 and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

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

Set Environment Variables

Configure the following environment variables:

Variable	Value
NODE_ENV	production
HOST	0.0.0.0
PORT	1337
PUBLIC_URL	https://your-app-name.klutch.sh
DATABASE_HOST	Your PostgreSQL host
DATABASE_PORT	5432
DATABASE_NAME	strapi
DATABASE_USERNAME	Your database username
DATABASE_PASSWORD	Your database password
APP_KEYS	Comma-separated keys (generate with openssl rand -base64 32)
API_TOKEN_SALT	Random string for API tokens
ADMIN_JWT_SECRET	Secret for admin JWT
JWT_SECRET	Secret for user JWT

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/public/uploads	50 GB	Uploaded media files

Deploy Your Application

Click Deploy to build and start Strapi.

Access Strapi Admin

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

Initial Configuration

Creating Admin Account

On first access:

1. Navigate to /admin
2. Create your super admin account
3. Complete initial setup

Content Type Builder

Create content structures:

1. Go to Content-Type Builder
2. Click Create new collection type
3. Define fields for your content
4. Save and restart

Common Field Types

Field Type	Use Case
Text	Titles, names, short text
Rich Text	Article content, descriptions
Number	Prices, quantities
Boolean	Toggles, flags
Date	Publication dates, events
Media	Images, files, videos
Relation	Links between content types
Component	Reusable field groups
Dynamic Zone	Flexible content blocks

API Usage

REST API

Access your content via REST:

GET /api/articles
GET /api/articles/:id
POST /api/articles
PUT /api/articles/:id
DELETE /api/articles/:id

GraphQL API

Enable GraphQL plugin for GraphQL queries:

query {
  articles {
    data {
      id
      attributes {
        title
        content
      }
    }
  }
}

API Tokens

Generate API tokens for secure access:

1. Go to Settings then API Tokens
2. Click Create new API Token
3. Set permissions and expiration
4. Use token in Authorization header

User Management

Roles and Permissions

Configure access control:

1. Navigate to Settings then Roles
2. Define custom roles
3. Set permissions per content type
4. Assign roles to users

Default Roles

Role	Description
Super Admin	Full access to everything
Editor	Create and edit content
Author	Create own content
Authenticated	Basic API access
Public	Unauthenticated API access

Plugin System

Installing Plugins

Add plugins to your Strapi project:

npm install @strapi/plugin-seo
npm install @strapi/plugin-graphql

Popular Plugins

Plugin	Purpose
GraphQL	GraphQL API support
SEO	SEO metadata management
i18n	Internationalization
Documentation	API documentation
Email	Email sending
Upload	Media upload providers

Media Management

Upload Providers

Configure cloud storage:

AWS S3:

config/plugins.js

module.exports = {
  upload: {
    config: {
      provider: 'aws-s3',
      providerOptions: {
        accessKeyId: process.env.AWS_ACCESS_KEY_ID,
        secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
        region: process.env.AWS_REGION,
        params: {
          Bucket: process.env.AWS_BUCKET,
        },
      },
    },
  },
};

Image Optimization

Strapi automatically generates responsive image formats.

Webhooks

Creating Webhooks

Trigger external services on content changes:

1. Go to Settings then Webhooks
2. Add webhook URL
3. Select trigger events
4. Configure headers if needed

Trigger Events

• Entry created
• Entry updated
• Entry deleted
• Entry published
• Entry unpublished

Troubleshooting

Admin Build Failed

• Check Node.js version compatibility
• Verify all dependencies installed
• Review build logs for errors

Database Connection Failed

• Verify connection string
• Check database server is accessible
• Ensure SSL settings are correct

Uploads Not Working

• Check persistent volume is mounted
• Verify directory permissions
• Review upload size limits

API Returning 403

• Check API permissions for role
• Verify API token is valid
• Review CORS configuration

Additional Resources

• Strapi Official Site
• Strapi Documentation
• Strapi GitHub Repository
• Strapi Marketplace
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Strapi on Klutch.sh gives you a powerful, customizable headless CMS with automatic builds, persistent storage, and secure HTTPS. Whether you’re building a blog, e-commerce site, or complex application, Strapi provides the flexibility to structure content your way while delivering it through modern APIs. With its intuitive admin panel and extensive plugin ecosystem, Strapi on Klutch.sh is a solid foundation for content-driven applications.