Deploying Thelia

Introduction

Thelia is a powerful, open-source e-commerce platform built on Symfony. Designed for flexibility and performance, Thelia provides everything needed to create professional online stores, from product management and order processing to advanced marketing tools and multi-language support. Its modular architecture allows extensive customization through themes and modules.

Key features of Thelia include:

Symfony Foundation: Built on the robust Symfony framework for reliability and extensibility
Modern Architecture: Clean, object-oriented codebase with RESTful API support
Advanced Product Management: Attributes, combinations, virtual products, and downloadable content
Multi-Store Support: Manage multiple storefronts from a single installation
Internationalization: Full multi-language and multi-currency support
Flexible Theming: Smarty-based templates with complete design freedom
Module System: Extend functionality with community and custom modules
SEO Optimization: Built-in tools for search engine visibility
Payment Integration: Support for major payment gateways
Order Management: Comprehensive order processing and fulfillment tools
Customer Management: Customer accounts, groups, and personalization

This guide walks you through deploying Thelia on Klutch.sh, configuring the database, and setting up your e-commerce store.

Why Deploy Thelia on Klutch.sh

Deploying Thelia on Klutch.sh provides several advantages for e-commerce:

Simplified Deployment: Klutch.sh handles container orchestration, allowing you to focus on your products and customers.

HTTPS by Default: Automatic SSL certificates ensure secure transactions and customer trust.

Persistent Storage: Reliable storage for products, orders, and customer data across deployments.

Scalable Resources: Adjust resources based on traffic, especially during sales and peak periods.

GitHub Integration: Version control your themes and customizations with automatic redeployments.

Prerequisites

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

A Klutch.sh account
A GitHub account with a repository for your Thelia configuration
Basic familiarity with Docker, PHP, and e-commerce concepts
A MySQL or MariaDB database (can be deployed on Klutch.sh)
Payment gateway credentials for accepting payments

Preparing Your Repository

Create a GitHub repository with the following structure:

thelia-deploy/
├── Dockerfile
├── .dockerignore
└── config/
    └── database.yml

Creating the Dockerfile

FROM php:8.1-apache

# Install system dependencies and PHP extensions
RUN apt-get update && apt-get install -y \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    libicu-dev \
    libxml2-dev \
    unzip \
    git \
    curl \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install gd mysqli pdo_mysql zip intl xml opcache \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

# Install Composer
COPY --from=composer:latest /usr/bin/composer /usr/bin/composer

# Enable Apache modules
RUN a2enmod rewrite headers

# Set working directory
WORKDIR /var/www/html

# Clone Thelia
RUN git clone --depth 1 https://github.com/thelia/thelia.git . \
    && composer install --no-dev --optimize-autoloader

# Set proper permissions
RUN chown -R www-data:www-data /var/www/html \
    && chmod -R 755 /var/www/html

# Configure PHP
RUN echo "upload_max_filesize = 64M" >> /usr/local/etc/php/conf.d/thelia.ini \
    && echo "post_max_size = 64M" >> /usr/local/etc/php/conf.d/thelia.ini \
    && echo "memory_limit = 512M" >> /usr/local/etc/php/conf.d/thelia.ini \
    && echo "max_execution_time = 300" >> /usr/local/etc/php/conf.d/thelia.ini

# Apache configuration
RUN echo '<Directory /var/www/html/web>\n\
    AllowOverride All\n\
    Require all granted\n\
</Directory>' > /etc/apache2/conf-available/thelia.conf \
    && a2enconf thelia

# Set document root to web directory
ENV APACHE_DOCUMENT_ROOT /var/www/html/web
RUN sed -ri -e 's!/var/www/html!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/sites-available/*.conf
RUN sed -ri -e 's!/var/www/!${APACHE_DOCUMENT_ROOT}!g' /etc/apache2/apache2.conf /etc/apache2/conf-available/*.conf

EXPOSE 80

CMD ["apache2-foreground"]

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_HOST`	Yes	-	MySQL database hostname
`DATABASE_NAME`	Yes	-	MySQL database name
`DATABASE_USER`	Yes	-	MySQL username
`DATABASE_PASSWORD`	Yes	-	MySQL password
`THELIA_DEBUG`	No	0	Enable debug mode (0 or 1)
`THELIA_ENV`	No	prod	Environment (prod or dev)

Deploying on Klutch.sh

Set Up MySQL Database

Thelia requires a MySQL or MariaDB database. Deploy MySQL as a separate app on Klutch.sh with persistent storage:

Mount Path	Size	Purpose
`/var/lib/mysql`	20 GB	Database storage

Push Your Repository to GitHub

Commit and push your Dockerfile and configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “thelia” or your store name.

Create the Thelia App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set the traffic type to HTTP with the internal port set to 80.

Set Environment Variables

Configure the database connection:

Variable	Value
`DATABASE_HOST`	Your MySQL host
`DATABASE_NAME`	thelia
`DATABASE_USER`	Your database user
`DATABASE_PASSWORD`	Your secure password
`THELIA_ENV`	prod

Attach Persistent Volumes

Add persistent storage for uploaded content:

Mount Path	Size	Purpose
`/var/www/html/local/media`	20 GB	Product images and media
`/var/www/html/cache`	2 GB	Template cache
`/var/www/html/log`	1 GB	Application logs

Deploy Your Application

Click Deploy to build and launch Thelia. Klutch.sh will provision HTTPS automatically.

Complete Installation Wizard

Access your site to complete the Thelia installation wizard.

Initial Configuration

Running the Installation Wizard

Navigate to https://your-app-name.klutch.sh/install
Enter database credentials
Create your admin account
Configure store settings
Choose a default template

Store Configuration

After installation, configure your store:

Access the admin panel at /admin
Set up your store name and contact information
Configure currencies and tax rules
Set up shipping zones and methods
Configure payment gateways

Product Catalog Setup

Build your product catalog:

Create product categories
Add product attributes (size, color, etc.)
Add products with images and descriptions
Configure product combinations (variants)
Set pricing and stock levels

E-Commerce Features

Payment Gateway Integration

Thelia supports various payment methods:

PayPal: Standard and Express checkout
Stripe: Credit card processing
Bank Transfer: Manual payment processing
Check Payment: Traditional payment method
Custom Gateways: Extend with modules

Shipping Configuration

Configure shipping options:

Weight-Based: Calculate shipping by order weight
Price-Based: Shipping based on order total
Zone-Based: Different rates for different regions
Carrier Integration: Connect to shipping carriers

Tax Configuration

Set up tax rules:

Define tax types (VAT, sales tax, etc.)
Create tax rules for different regions
Assign tax rules to products
Configure tax display preferences

Theme Customization

Working with Themes

Thelia uses Smarty templates:

Themes are located in /templates/frontOffice/
Modify existing themes or create new ones
Override default templates selectively
Use CSS and JavaScript for styling

Creating Custom Themes

Structure of a Thelia theme:

templates/frontOffice/mytheme/
├── assets/
│   ├── css/
│   └── js/
├── includes/
├── layouts/
└── templates/

Module Development

Installing Modules

Extend Thelia with modules:

Download modules from the marketplace
Place in /local/modules/
Activate through the admin panel
Configure module settings

Essential Modules

Common modules for Thelia:

Google Analytics: Track visitor behavior
Social Login: Facebook, Google authentication
Mailchimp: Newsletter integration
Reviews: Product review system
Advanced Search: Enhanced search functionality

Production Best Practices

Security Recommendations

Strong Admin Password: Use complex passwords for admin accounts
SSL Everywhere: Ensure all pages use HTTPS
Regular Updates: Keep Thelia and modules updated
Payment Security: Use PCI-compliant payment gateways
Database Backups: Regular automated backups

Performance Optimization

Enable Caching: Configure Thelia’s caching system
Image Optimization: Compress product images
CDN Integration: Use a CDN for static assets
Database Optimization: Regular database maintenance
Opcache: Enable PHP opcache for better performance

Backup Strategy

Protect your e-commerce data:

Daily database backups
Regular media file backups
Version control themes and customizations
Test restoration procedures

Troubleshooting

Installation Errors

Verify database credentials
Check PHP extension requirements
Ensure file permissions are correct
Review installation logs

Product Images Not Displaying

Check media directory permissions
Verify image file formats
Clear template cache
Check storage configuration

Payment Processing Issues

Verify payment gateway credentials
Check API endpoint configuration
Review payment logs
Test in sandbox mode first

Performance Problems

Enable caching mechanisms
Optimize database queries
Review server resource allocation
Check for module conflicts

Additional Resources

Conclusion

Deploying Thelia on Klutch.sh provides a robust foundation for building professional e-commerce stores. With its flexible architecture, extensive customization options, and comprehensive feature set, Thelia can power everything from small boutiques to large-scale online retailers. The combination of Thelia’s e-commerce capabilities and Klutch.sh’s reliable infrastructure ensures your store remains fast, secure, and always available for your customers.