Deploying an Aimeos App

Introduction

Aimeos is a high-performance, open-source e-commerce framework for PHP that provides a complete online shop solution with a modern architecture. Built on Laravel, Symfony, or as a standalone framework, Aimeos offers exceptional performance, scalability, and flexibility for building custom e-commerce applications.

Aimeos is renowned for its:

High Performance: Optimized for speed with caching, lazy loading, and efficient database queries
Modern Architecture: Built on PSR standards with dependency injection and service-oriented design
Multi-Channel Support: Manage products across web shops, mobile apps, and marketplaces from one backend
Extensible Framework: Plugin-based architecture allows unlimited customization
SEO-Friendly: Built-in SEO features including clean URLs, meta tags, and sitemap generation
Internationalization: Multi-language and multi-currency support out of the box
Product Management: Advanced catalog management with variants, attributes, and media handling
Order Processing: Complete order management with payment and shipping integration
Customer Management: Customer accounts, wishlists, and order history
Admin Interface: Powerful admin panel for managing products, orders, and customers

Common use cases include online stores, B2B marketplaces, multi-vendor platforms, subscription services, and custom e-commerce solutions requiring high performance and flexibility.

This comprehensive guide walks you through deploying Aimeos on Klutch.sh using a Dockerfile, including detailed installation steps, sample code, persistent storage configuration, and production-ready best practices.

Prerequisites

Before you begin, ensure you have the following:

A Klutch.sh account
A GitHub account with a repository for your Aimeos project
Docker installed locally for testing (optional but recommended)
A MySQL or MariaDB database (can be deployed separately on Klutch.sh or use an external database)
Basic understanding of PHP, Composer, and e-commerce concepts

Installation and Setup

Step 1: Create Your Project Directory

First, create a new directory for your Aimeos deployment project:

mkdir aimeos-klutch
cd aimeos-klutch
git init

Step 2: Install Aimeos

Aimeos can be installed via Composer. Create a composer.json file:

{
    "name": "mycompany/aimeos-shop",
    "description": "Aimeos e-commerce shop",
    "type": "project",
    "require": {
        "php": ">=8.1",
        "aimeos/aimeos-laravel": "^2023.10"
    },
    "autoload": {
        "psr-4": {
            "App\\": "app/"
        }
    },
    "config": {
        "optimize-autoloader": true,
        "preferred-install": "dist"
    },
    "minimum-stability": "stable",
    "prefer-stable": true
}

Alternatively, if you’re using Aimeos as a standalone framework, you can use the Aimeos distribution:

composer create-project aimeos/aimeos:~2023.10

Step 3: Create the Dockerfile

Create a Dockerfile in your project root directory. This will define your Aimeos container configuration:

FROM php:8.2-apache

# Install system dependencies and PHP extensions required by Aimeos
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libjpeg-dev \
    libfreetype6-dev \
    libzip-dev \
    libicu-dev \
    libonig-dev \
    libxml2-dev \
    unzip \
    zip \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) \
        pdo_mysql \
        mysqli \
        gd \
        intl \
        zip \
        opcache \
        mbstring \
        xml \
        bcmath \
    && rm -rf /var/lib/apt/lists/*

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

# Enable Apache mod_rewrite for clean URLs
RUN a2enmod rewrite headers

# Set working directory
WORKDIR /var/www/html

# Copy composer files
COPY composer.json composer.lock* ./

# Install PHP dependencies
RUN composer install --no-dev --optimize-autoloader --no-interaction --no-scripts

# Copy application files
COPY . .

# Run Composer scripts (if any) and set permissions
RUN composer dump-autoload --optimize && \
    chown -R www-data:www-data /var/www/html && \
    chmod -R 755 /var/www/html

# Configure PHP for production
RUN echo "memory_limit = 512M" > /usr/local/etc/php/conf.d/memory.ini && \
    echo "upload_max_filesize = 20M" > /usr/local/etc/php/conf.d/uploads.ini && \
    echo "post_max_size = 20M" >> /usr/local/etc/php/conf.d/uploads.ini && \
    echo "max_execution_time = 300" > /usr/local/etc/php/conf.d/execution.ini

# Configure Apache
RUN echo '<VirtualHost *:8080>\n\
    DocumentRoot /var/www/html/public\n\
    <Directory /var/www/html/public>\n\
        AllowOverride All\n\
        Require all granted\n\
    </Directory>\n\
    ErrorLog ${APACHE_LOG_DIR}/error.log\n\
    CustomLog ${APACHE_LOG_DIR}/access.log combined\n\
</VirtualHost>' > /etc/apache2/sites-available/000-default.conf

# Change Apache port to 8080
RUN sed -i 's/Listen 80/Listen 8080/' /etc/apache2/ports.conf

# Expose port 8080
EXPOSE 8080

# Set environment variables
ENV APACHE_DOCUMENT_ROOT=/var/www/html/public
ENV PHP_MEMORY_LIMIT=512M

# Start Apache
CMD ["apache2-foreground"]

Note: This Dockerfile configures Aimeos to run on port 8080, which will be your internal port in Klutch.sh. The application files are served from the public directory, which is standard for Aimeos installations.

Step 4: Create Sample Application Code

Create a basic Aimeos application structure. Here’s a minimal example:

public/index.php (entry point):

<?php
require __DIR__ . '/../vendor/autoload.php';

// Bootstrap your Aimeos application
$app = require_once __DIR__ . '/../bootstrap/app.php';

// Run the application
$app->run();

config/app.php (basic configuration):

<?php
return [
    'name' => env('APP_NAME', 'Aimeos Shop'),
    'env' => env('APP_ENV', 'production'),
    'debug' => env('APP_DEBUG', false),
    'url' => env('APP_URL', 'https://example-app.klutch.sh'),
    'timezone' => env('APP_TIMEZONE', 'UTC'),
    'locale' => env('APP_LOCALE', 'en'),
    'fallback_locale' => env('APP_FALLBACK_LOCALE', 'en'),
    'key' => env('APP_KEY', ''),
    'cipher' => 'AES-256-CBC',
];

config/database.php (database configuration):

<?php
return [
    'default' => env('DB_CONNECTION', 'mysql'),
    'connections' => [
        'mysql' => [
            'driver' => 'mysql',
            'host' => env('DB_HOST', 'localhost'),
            'port' => env('DB_PORT', 3306),
            'database' => env('DB_DATABASE', 'aimeos'),
            'username' => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
            'charset' => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix' => '',
            'strict' => true,
            'engine' => 'InnoDB',
        ],
    ],
];

bootstrap/app.php (application bootstrap):

<?php
$app = new \Aimeos\App();

// Load configuration
$app->config(require __DIR__ . '/../config/app.php');
$app->config(require __DIR__ . '/../config/database.php');

// Set up error handling
if (!$app->config('app.debug')) {
    error_reporting(0);
    ini_set('display_errors', 0);
}

return $app;

Step 5: Create .env.example File

Create a .env.example file with required environment variables:

APP_NAME=Aimeos Shop
APP_ENV=production
APP_DEBUG=false
APP_URL=https://example-app.klutch.sh
APP_KEY=base64:your-generated-key-here

DB_CONNECTION=mysql
DB_HOST=your-database-host
DB_PORT=3306
DB_DATABASE=aimeos
DB_USERNAME=your-db-user
DB_PASSWORD=your-db-password

CACHE_DRIVER=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

AIMEOS_SHOP_PATH=/var/www/html/public
AIMEOS_ADMIN_PATH=/var/www/html/public/admin

Step 6: Test Locally (Optional)

Before deploying to Klutch.sh, you can test your Aimeos setup locally:

# Build the Docker image
docker build -t my-aimeos .

# Run the container (assuming you have a database running)
docker run -d \
  --name aimeos-test \
  -p 8080:8080 \
  -e DB_HOST=host.docker.internal \
  -e DB_DATABASE=aimeos \
  -e DB_USERNAME=root \
  -e DB_PASSWORD=password \
  -v $(pwd)/storage:/var/www/html/storage \
  my-aimeos

# Check if the application is running
curl http://localhost:8080

Note: For local development with a database, you can use Docker Compose to run both Aimeos and MySQL together. Docker Compose is only for local development; Klutch.sh does not support Docker Compose for deployment.

Step 7: Push to GitHub

Commit your Aimeos project files to your GitHub repository:

git add .
git commit -m "Initial Aimeos Docker setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/yourusername/aimeos-klutch.git
git push -u origin main

Deploying to Klutch.sh

Now that your Aimeos project is ready and pushed to GitHub, follow these steps to deploy it on Klutch.sh with persistent storage.

Deployment Steps

Log in to Klutch.sh

Navigate to klutch.sh/app and sign in to your account.
Create a New Project

Go to Create Project and give your project a meaningful name (e.g., “Aimeos E-commerce Store”).
Create a New App

Navigate to Create App and configure the following settings:
Select Your Repository
- Choose GitHub as your Git source
- Select the repository containing your Dockerfile
- Choose the branch you want to deploy (usually main or master)
Klutch.sh will automatically detect the Dockerfile in your repository root and use it for deployment.
Configure Traffic Type
- Traffic Type: Select HTTP (Aimeos is a web application)
- Internal Port: Set to 8080 (the port your Aimeos container listens on, as defined in your Dockerfile)
Set Environment Variables

Add the following environment variables for your Aimeos configuration:
- APP_NAME: Your shop name (e.g., My Aimeos Shop)
- APP_ENV: Set to production
- APP_DEBUG: Set to false for production
- APP_URL: Your Klutch.sh app URL (e.g., https://example-app.klutch.sh)
- APP_KEY: A base64-encoded 32-character key (generate one using openssl rand -base64 32)
- DB_HOST: Your database host (if using a Klutch.sh database app, use the app URL like example-db.klutch.sh)
- DB_PORT: Database port (for Klutch.sh TCP apps, use 8000 externally, but the internal port in your database app should be 3306 for MySQL)
- DB_DATABASE: Your database name
- DB_USERNAME: Database username
- DB_PASSWORD: Database password
- CACHE_DRIVER: Set to file or redis (if using Redis)
- SESSION_DRIVER: Set to file or redis
- TZ: Your timezone (e.g., UTC or America/New_York)
Attach Persistent Volumes

Aimeos requires persistent storage for several directories to ensure data persists across deployments:

Storage Volume:
- Mount Path: /var/www/html/storage
- Size: Start with 10GB minimum (20GB+ recommended for production with media files)
This volume stores:
- Uploaded product images and media files
- Cache files
- Log files
- Session data
- Generated files
Optional - Public Uploads Volume:
- Mount Path: /var/www/html/public/uploads
- Size: 10GB+ (for user-uploaded content and product media)
Note: For production stores with many products and media files, allocate sufficient storage. You can increase volume size later if needed.
Configure Additional Settings
- Region: Select the region closest to your users for optimal performance
- Compute Resources: Aimeos can be resource-intensive; allocate at least:
  - CPU: 2+ cores recommended
  - Memory: 2GB minimum (4GB+ recommended for production workloads)
- Instances: Start with 1 instance (you can scale horizontally later if needed)
Deploy Your Application

Click “Create” to start the deployment. Klutch.sh will:
- Automatically detect your Dockerfile in the repository root
- Build the Docker image
- Attach the persistent volume(s)
- Start your Aimeos container
- Assign a URL for external access
Note: The first deployment may take several minutes as it builds the Docker image and installs dependencies.
Initialize Aimeos Database

After deployment, you’ll need to set up your Aimeos database schema. Connect to your database and run the Aimeos setup commands, or use the Aimeos setup wizard if available through the web interface.
Access Your Application

Once deployment is complete, you’ll receive a URL like example-app.klutch.sh. Visit this URL to access your Aimeos shop.

Sample Code: Getting Started with Aimeos

Here are some examples to help you get started with Aimeos development:

Example 1: Basic Product Listing

<?php
use Aimeos\MShop\Context\Item\Iface as Context;
use Aimeos\MShop\Product\Manager\Iface as ProductManager;

class ProductController
{
    public function listProducts(Context $context)
    {
        $productManager = \Aimeos\MShop::create($context, 'product');

        $search = $productManager->filter();
        $search->setConditions($search->compare('==', 'product.status', 1));
        $search->setSortations([$search->sort('+', 'product.label')]);

        $products = $productManager->search($search);

        return $products;
    }
}

Example 2: Creating a Product

<?php
use Aimeos\MShop\Context\Item\Iface as Context;

class ProductService
{
    public function createProduct(Context $context, array $data)
    {
        $productManager = \Aimeos\MShop::create($context, 'product');
        $product = $productManager->create();

        $product->setLabel($data['label']);
        $product->setType('default');
        $product->setStatus(1);
        $product->setCode($data['code']);

        // Set price
        $priceManager = \Aimeos\MShop::create($context, 'price');
        $price = $priceManager->create();
        $price->setType('default');
        $price->setCurrencyId('USD');
        $price->setValue($data['price']);
        $price->setQuantity(1);

        $product->addListItem('price', 'default', $price);

        // Save product
        $productManager->save($product);

        return $product;
    }
}

Example 3: Shopping Cart Operations

<?php
use Aimeos\MShop\Context\Item\Iface as Context;
use Aimeos\MShop\Order\Item\Base\Iface as Basket;

class CartService
{
    public function addToCart(Context $context, Basket $basket, string $productId, int $quantity = 1)
    {
        $productManager = \Aimeos\MShop::create($context, 'product');
        $product = $productManager->get($productId);

        $basket->addProduct($product, $quantity);

        return $basket;
    }

    public function getCartTotal(Basket $basket): float
    {
        $price = $basket->getPrice();
        return $price->getValue() + $price->getCosts();
    }
}

Example 4: JavaScript API Integration

// Frontend JavaScript example for Aimeos API

async function fetchProducts() {
  try {
    const response = await fetch('https://example-app.klutch.sh/jsonapi/product', {
      method: 'GET',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/vnd.api+json'
      }
    });

    const data = await response.json();
    console.log('Products:', data);
    return data;
  } catch (error) {
    console.error('Error fetching products:', error);
  }
}

async function addToCart(productId, quantity = 1) {
  try {
    const response = await fetch('https://example-app.klutch.sh/jsonapi/basket/product', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/vnd.api+json'
      },
      body: JSON.stringify({
        data: {
          type: 'basket.product',
          attributes: {
            'product.id': productId,
            quantity: quantity
          }
        }
      })
    });

    const data = await response.json();
    console.log('Added to cart:', data);
    return data;
  } catch (error) {
    console.error('Error adding to cart:', error);
  }
}

Production Best Practices

Security Recommendations

Enable HTTPS: Always use HTTPS in production (Klutch.sh provides TLS certificates)
Secure Environment Variables: Store all sensitive credentials as environment variables in Klutch.sh
Disable Debug Mode: Set APP_DEBUG=false in production
Strong App Key: Generate a strong APP_KEY using openssl rand -base64 32
Database Security: Use strong database passwords and restrict database access
File Permissions: Ensure proper file permissions (the Dockerfile sets these automatically)
Regular Updates: Keep Aimeos and dependencies updated with security patches
Input Validation: Always validate and sanitize user input
CSRF Protection: Enable CSRF protection for all forms
SQL Injection Prevention: Use Aimeos’s built-in query builders and prepared statements

Performance Optimization

Enable Opcache: The Dockerfile includes Opcache configuration for PHP
Caching Strategy: Use Redis or Memcached for caching in production
CDN Integration: Serve static assets through a CDN
Database Optimization: Regularly optimize database tables and indexes
Image Optimization: Compress and optimize product images before upload
Lazy Loading: Implement lazy loading for product images and content
Database Connection Pooling: Configure appropriate connection pool sizes
Session Storage: Use Redis for session storage in multi-instance deployments
Query Optimization: Monitor and optimize slow database queries

Monitoring and Maintenance

Monitor your Aimeos application for:

Application Logs: Check logs in Klutch.sh dashboard for errors
Database Performance: Monitor query performance and slow queries
Storage Usage: Monitor persistent volume usage and plan for growth
Response Times: Track API response times and page load speeds
Error Rates: Monitor 4xx and 5xx error rates
Resource Usage: Track CPU and memory usage in Klutch.sh dashboard

Regular maintenance tasks:

Backup Database: Regularly backup your database
Backup Media Files: Backup uploaded product images and media files
Update Dependencies: Keep Composer dependencies updated
Clean Cache: Regularly clear application cache
Review Logs: Review application and error logs regularly
Security Audits: Perform regular security audits

Troubleshooting

Application Not Loading

Verify the app’s Traffic Type is HTTP
Check that the internal port is set to 8080 and matches your Dockerfile
Review build and runtime logs in the Klutch.sh dashboard
Ensure the public directory is correctly configured as the document root

Database Connection Issues

Verify database environment variables are set correctly
For Klutch.sh database apps, use the app URL as the host and port 8000 externally
Check that the database is accessible from your Aimeos app
Verify database credentials and permissions

File Upload Issues

Ensure persistent volume is mounted at /var/www/html/storage
Check file permissions on the storage directory
Verify upload_max_filesize and post_max_size PHP settings
Ensure sufficient disk space in the persistent volume

Performance Issues

Enable caching (Redis recommended for production)
Optimize database queries and add indexes
Review and optimize product images
Consider increasing compute resources in Klutch.sh
Enable Opcache (already configured in the Dockerfile)

Customizations Not Persisting

Ensure persistent volumes are correctly mounted
Verify files are being written to mounted volume paths
Check file permissions on persistent volumes
Confirm volume sizes are sufficient

Learn more about deploying applications on Klutch.sh in Deployments
Understand traffic types, ports, and routing in Networking
Explore how to work with storage in Volumes
Browse the full platform documentation at Klutch.sh Documentation
For Aimeos-specific details, see the official Aimeos Documentation
Learn about Aimeos architecture and best practices at Aimeos Architecture Guide

Conclusion

Deploying Aimeos to Klutch.sh with a Dockerfile provides a powerful, scalable e-commerce solution with persistent storage, automatic deployments, and production-ready configuration. By following this guide, you’ve set up a high-performance Aimeos store with proper data persistence, security configurations, and the ability to handle real-world e-commerce workloads.

Aimeos’s modern architecture, exceptional performance, and extensive customization options make it an excellent choice for building custom e-commerce applications. Your store is now ready to handle product catalogs, orders, customers, and all the features needed for a successful online business.

Remember to follow the production best practices outlined in this guide, regularly monitor your application performance, and adjust resources as your store grows. With proper configuration, monitoring, and maintenance, Aimeos on Klutch.sh will provide a reliable, high-performance foundation for your e-commerce business.