Deploying Squidex

Introduction

Squidex is an open-source headless CMS built on .NET that provides a powerful content management platform with an API-first approach. It enables developers to create and manage structured content that can be delivered to any frontend, mobile app, or IoT device through REST or GraphQL APIs.

Built with modern technologies and designed for flexibility, Squidex offers features typically found only in enterprise CMS solutions while remaining completely open source and self-hostable.

Key highlights of Squidex:

• API-First Design: REST and GraphQL APIs for content delivery
• Schema Builder: Visual schema editor for content types
• Asset Management: Built-in digital asset management with transformations
• Multi-Language: Full localization support for content
• Workflows: Custom content workflows and approval processes
• Scripting: Server-side scripting for validation and transformations
• Scheduled Publishing: Schedule content to publish automatically
• Versioning: Full content history with restore capabilities
• Roles and Permissions: Fine-grained access control
• Webhooks: Trigger external services on content changes
• Full-Text Search: Powerful content search with Elasticsearch
• Open Source: MIT licensed with active development

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

Why Deploy Squidex on Klutch.sh

Deploying Squidex on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles the .NET application deployment automatically.

Persistent Storage: Content, schemas, and assets persist across deployments.

HTTPS by Default: Secure API access with automatic SSL certificates.

GitHub Integration: Version control your configuration 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 the CMS API.

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

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• MongoDB database (can be deployed on Klutch.sh or use cloud service)
• Basic familiarity with Docker and CMS concepts
• (Optional) A custom domain for your Squidex instance

Deploying Squidex on Klutch.sh

Create a GitHub Repository

Create a new GitHub repository for your Squidex deployment.

Create Your Dockerfile

Create a Dockerfile in your repository:

FROM squidex/squidex:latest

# Squidex runs on port 80 by default
# Configuration is done through environment variables

EXPOSE 80

HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
  CMD curl -f http://localhost:80/healthz || exit 1

Push Your Repository to GitHub

Commit and push your 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 80

Set Environment Variables

Configure the following environment variables:

Variable	Value
URLS__BASEURL	https://your-app-name.klutch.sh
EVENTSTORE__MONGODB__CONFIGURATION	MongoDB connection string
STORE__MONGODB__CONFIGURATION	MongoDB connection string
IDENTITY__ADMINEMAIL	Admin email address
IDENTITY__ADMINPASSWORD	Initial admin password
IDENTITY__GOOGLECLIENT	(Optional) Google OAuth client ID
IDENTITY__GOOGLESECRET	(Optional) Google OAuth secret

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/app/Assets	50 GB	Uploaded assets and media

Deploy Your Application

Click Deploy to build and start Squidex.

Access Squidex

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

Initial Configuration

Logging In

Navigate to your Squidex URL and log in with the admin credentials configured in the environment variables.

Creating Your First App

In Squidex, an “App” is a content project:

1. Click New App on the dashboard
2. Enter an app name (URL-friendly)
3. Configure app settings

Building Schemas

Create content types with the schema builder:

1. Navigate to Schemas
2. Click Add Schema
3. Name your schema (e.g., “blog-posts”)
4. Add fields with the visual editor

Field Types

Field Type	Use Case
String	Text, titles, descriptions
Number	Prices, quantities, ratings
Boolean	Toggles, flags
DateTime	Dates, timestamps
Assets	Images, files, media
References	Links to other content
Array	Lists of items
Component	Nested structures
Tags	Categorization
Geolocation	Coordinates

Content Management

Creating Content

1. Navigate to your schema under Contents
2. Click New
3. Fill in the content fields
4. Save as draft or publish

Content Workflows

Configure custom workflows:

1. Go to Settings then Workflows
2. Define workflow states (Draft, Review, Published)
3. Configure transitions and permissions

Localization

For multi-language content:

1. Enable languages in Settings then Languages
2. Mark schema fields as localizable
3. Edit content in each language

API Access

REST API

Access content via REST:

GET /api/content/{app}/{schema}
GET /api/content/{app}/{schema}/{id}
POST /api/content/{app}/{schema}

GraphQL API

Use GraphQL for flexible queries:

POST /api/content/{app}/graphql

Authentication

Generate API clients:

1. Go to Settings then Clients
2. Click Add Client
3. Note the client ID and secret
4. Use OAuth for authentication

Asset Management

Uploading Assets

1. Navigate to Assets
2. Drag and drop files or click to upload
3. Organize with folders

Image Transformations

Transform images via URL parameters:

/api/assets/{id}?width=800&height=600&mode=Crop

Webhooks

Creating Webhooks

Trigger external services on content changes:

1. Go to Schemas then select your schema
2. Navigate to Webhooks
3. Add webhook URL and configure triggers

Webhook Events

• Content created
• Content updated
• Content published
• Content deleted
• Asset uploaded

Troubleshooting

MongoDB Connection Failed

• Verify connection string format
• Check MongoDB is accessible
• Ensure database user has proper permissions

Assets Not Loading

• Verify asset volume is mounted
• Check file permissions
• Review asset storage configuration

API Returns 401

• Verify client credentials
• Check token expiration
• Ensure client has proper permissions

Additional Resources

• Squidex Official Site
• Squidex Documentation
• Squidex GitHub Repository
• Squidex API Documentation
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Squidex on Klutch.sh gives you a powerful, enterprise-grade headless CMS with automatic builds, persistent storage, and secure HTTPS. With its flexible schema system, powerful API, and comprehensive asset management, Squidex provides everything you need to manage content for modern applications while keeping full control over your data.