Deploying Neos

Introduction

Neos is a modern content application platform that goes beyond traditional CMS functionality. Built on the Flow PHP framework, Neos provides an intuitive in-place editing experience that lets content editors work directly on the visual representation of their content, while developers enjoy a powerful, API-first architecture.

Unlike traditional CMSs that separate content creation from presentation, Neos allows editors to see exactly how their content will appear as they create it. The platform supports complex content structures, multi-site management, and integrates seamlessly with modern development workflows.

Key highlights of Neos:

• In-Place Editing: Edit content directly in the visual context where it appears
• Content Dimensions: Manage content variants for languages, regions, and personas
• React-Based UI: Modern, responsive backend interface
• Semantic Content: Structured content model with powerful relationships
• Multi-Site: Manage multiple websites from a single installation
• Media Management: Built-in digital asset management
• Workspaces: Review and approve content before publishing
• API-First: Headless CMS capabilities for decoupled frontends
• Extensible: Rich ecosystem of packages and integrations

This guide walks through deploying Neos on Klutch.sh using Docker.

Why Deploy Neos on Klutch.sh

Deploying Neos on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh handles containerization and infrastructure, letting you focus on building great content experiences.

Persistent Storage: Content, media, and configuration persist across deployments in attached volumes.

HTTPS by Default: Automatic SSL certificates for secure content management.

Scalable Resources: Adjust resources based on traffic and content complexity.

GitHub Integration: Push configuration changes to automatically redeploy.

Prerequisites

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

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic familiarity with PHP applications and Docker
• (Optional) A custom domain for your Neos site

Understanding Neos Architecture

Neos is built on several components:

Flow Framework: PHP framework providing the application foundation with dependency injection, MVC, and persistence.

Content Repository: Stores content as nodes in a graph structure with support for workspaces and dimensions.

Fusion Rendering: Template language for combining content with presentation.

React Backend: Modern administrative interface for content management.

Media Library: Asset management for images, documents, and files.

Preparing Your Repository

Create a GitHub repository for your Neos deployment.

Repository Structure

neos-deploy/
├── Dockerfile
├── .dockerignore
└── Configuration/
    └── Settings.yaml

Creating the Dockerfile

FROM neos/neos:latest

# Environment configuration
ENV FLOW_CONTEXT=Production
ENV NEOS_FLOW_DB_HOST=${DB_HOST}
ENV NEOS_FLOW_DB_NAME=${DB_NAME}
ENV NEOS_FLOW_DB_USER=${DB_USER}
ENV NEOS_FLOW_DB_PASSWORD=${DB_PASSWORD}

# Expose web interface
EXPOSE 8080

# Volumes for persistent data
VOLUME ["/data", "/app/Data"]

Creating Settings Configuration

Create Configuration/Settings.yaml:

Neos:
  Flow:
    persistence:
      backendOptions:
        driver: pdo_mysql
        host: '%env:DB_HOST%'
        dbname: '%env:DB_NAME%'
        user: '%env:DB_USER%'
        password: '%env:DB_PASSWORD%'
        charset: utf8mb4

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
.DS_Store
node_modules/

Deploying Neos on Klutch.sh

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a project named “neos” or your site name.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Neos serves web content over HTTP:

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

Set Environment Variables

Configure database and application settings:

Variable	Value
DB_HOST	Your MySQL/MariaDB host
DB_NAME	neos
DB_USER	Database username
DB_PASSWORD	Secure database password
FLOW_CONTEXT	Production

Attach Persistent Volumes

Configure storage for content and assets:

Mount Path	Recommended Size	Purpose
/app/Data/Persistent	20 GB	Uploaded media and assets
/app/Data/Logs	1 GB	Application logs

Deploy Your Application

Click Deploy to build and start your Neos instance.

Access Neos

Visit https://your-app-name.klutch.sh/neos to access the backend.

Initial Setup

First-Time Configuration

On first access:

1. Run the setup wizard at /setup
2. Create administrator account
3. Configure site package
4. Import demo content or start fresh

Creating Your First Site

Set up your site:

1. Log into the Neos backend
2. Create a new site package or use existing one
3. Configure site name and domain
4. Start creating content

User Management

Add content editors:

1. Go to User Management
2. Create user accounts
3. Assign appropriate roles
4. Configure workspace permissions

In-Place Editing

Working with Content

Neos’s visual editing:

1. Navigate to any page
2. Click elements to edit directly
3. See changes in real-time context
4. Changes are saved to workspace

Content Elements

Add various content types:

• Text and headlines
• Images and media
• Multi-column layouts
• Navigation menus
• Custom content types

Publishing Workflow

Manage content lifecycle:

1. Make changes in your workspace
2. Preview changes
3. Review differences
4. Publish to live site

Content Dimensions

Multi-Language Sites

Manage translations:

1. Configure language dimensions
2. Create content in primary language
3. Translate to additional languages
4. Automatic fallback handling

Market/Region Variants

Customize by audience:

1. Define dimension presets
2. Create targeted content variants
3. Configure fallback chains
4. Preview different dimensions

Media Management

Asset Library

Organize digital assets:

1. Upload images, documents, videos
2. Organize into collections
3. Tag for easy discovery
4. Automatic thumbnail generation

Image Editing

Built-in image manipulation:

• Cropping and resizing
• Aspect ratio presets
• Focal point selection
• Filter effects

Development

Site Packages

Customize Neos:

1. Create custom site package
2. Define content types
3. Create Fusion templates
4. Configure backend modules

Fusion Templating

Example Fusion:

prototype(My.Site:Content.Text) < prototype(Neos.Neos:ContentComponent) {
    renderer = afx`
        <div class="text-block">
            {props.text}
        </div>
    `
}

Custom Content Types

Define in NodeTypes:

'My.Site:Content.Hero':
  superTypes:
    'Neos.Neos:Content': true
  properties:
    headline:
      type: string
    image:
      type: Neos\Media\Domain\Model\ImageInterface

Multi-Site Management

Multiple Sites

Manage several sites:

1. Create separate site packages
2. Configure domain mappings
3. Share or separate assets
4. Unified user management

Domain Configuration

Map domains to sites:

1. Go to Site Management
2. Add domains to sites
3. Configure primary domains
4. Handle redirects

Production Best Practices

Performance

Optimize Neos:

• Enable caching in Production context
• Configure CDN for assets
• Optimize database queries
• Monitor resource usage

Security

Secure your installation:

• Keep Neos updated
• Strong admin passwords
• Regular security audits
• Proper file permissions

Backup Strategy

Protect your content:

1. Database backups (content)
2. File system backups (assets)
3. Version control for code
4. Test restore procedures

Troubleshooting

Blank Page / Errors

• Check FLOW_CONTEXT setting
• Review logs in Data/Logs
• Verify database connection
• Check file permissions

Slow Performance

• Verify Production context
• Check caching configuration
• Monitor database queries
• Review error logs

Login Issues

• Clear session data
• Verify user credentials
• Check database connectivity
• Review authentication logs

Asset Problems

• Verify persistent volume mount
• Check upload limits
• Review media folder permissions
• Check available storage

Additional Resources

• Official Neos Website
• Neos Documentation
• Neos GitHub Repository
• Neos Forum
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Neos on Klutch.sh gives you access to a sophisticated content management platform with modern editing capabilities. The in-place editing experience empowers content creators while the powerful architecture supports complex content requirements.

Whether you’re building a corporate website, multi-language portal, or headless content API, Neos on Klutch.sh provides the foundation for sophisticated content management with simplified deployment and reliable hosting.