Skip to main content
page last edited on 5 October 2022

Server Setup

Version: 5.5.0

You can find samples of the nginx and apache setup in the /docs folder of the X-Cart software package.

Since X-Cart is a Symfony 5.4-based application, the general software setup is similar to Symfony despite minor alterations. Hence you can refer to the Symfony 5.4 official documentation in addition to this article.

The public directory

The public directory is the home of your application's public and static files, including images, stylesheets, and JavaScript files. It is also where the front controller (index.php) lives.

The server document root must be configured in the /public subfolder of your X-Cart root. You must also ensure both index.php and service.php are executable.

If you upgraded your software from X-Cart 5.4.1.x and need to reconfigure the server, don't forget to adjust the XCART_PUBLIC_DIR variable in the .env.local file on the server.

XCART_PUBLIC_DIR=0

After that, redeploy the store on the System → Cache Management page of your store's Admin area or use the ./bin/service xcst:rebuild operation in the console.

Apache

Below is the example configuration to get your application running under Apache 2.4 with PHP-FPM.

If you have X-Cart installed into a web directory, see the web directory example configuration.

## X-Cart 5 apache 2.4 sample configuration
#
# Replace placeholders:
# {{public-full-path}} - real full path of public dir
#
# Example
#
# Xcart installation path: /var/www/xcart
# Expected URL: https://localhost/
#
# public-full-path: /var/www/xcart/public
#

LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

ServerName xcart.test

<VirtualHost *:80>
ServerAdmin admin@example.com

DocumentRoot {{public-full-path}}

<Directory {{public-full-path}}>
DirectoryIndex index.php

Options Indexes FollowSymLinks
AllowOverride All
Require all granted
FallbackResource /index.php

<IfModule mod_rewrite.c>
Options -MultiViews

RewriteEngine On

RewriteRule ^sitemap.xml(\?.+)?$ /?target=sitemap [NC,L,QSA]

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [QSA,L]
</IfModule>

</Directory>

<FilesMatch ".php$">
SetHandler "proxy:fcgi://127.0.0.1:9000"
</FilesMatch>

</VirtualHost>

Web directory

## X-Cart 5 apache 2.4 sample configuration
#
# Replace placeholders:
# {{web-dir}} - web dir value
# {{root-full-path}} - real full path of host handler app
# {{public-full-path}} - real full path of public dir (must not be a subdir of root-full-path)
#
# Example
#
# Host handler app path: /var/www/http
# Xcart installation path: /var/www/xcart
# Expected URL: https://localhost/some/dir
#
# web-dir: some/dir
# root-full-path: /var/www/http
# public-full-path: /var/www/xcart/public
#

LoadModule proxy_module lib/httpd/modules/mod_proxy.so
LoadModule proxy_fcgi_module lib/httpd/modules/mod_proxy_fcgi.so
LoadModule rewrite_module lib/httpd/modules/mod_rewrite.so

DocumentRoot {{root-full-path}}

ServerName xcart.test

<VirtualHost *:80>
ServerAdmin admin@example.com

Alias /{{web-dir}} {{public-full-path}}

<Directory {{public-full-path}}>
DirectoryIndex index.php

Options Indexes FollowSymLinks
AllowOverride All
Require all granted
FallbackResource /index.php

<IfModule mod_rewrite.c>
Options -MultiViews

RewriteEngine On

RewriteRule ^sitemap.xml(\?.+)?$ /?target=sitemap [NC,L,QSA]

RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [QSA,L]
</IfModule>

</Directory>

<Directory {{root-full-path}}>
AllowOverride All
Require all granted
</Directory>

<FilesMatch ".php$">
SetHandler "proxy:fcgi://127.0.0.1:9000"
</FilesMatch>

</VirtualHost>

Please carefully check the above configuration sample and adapt it to your server environment.

You can find the sample of an Apache server configuration for a store located in a subfolder but not in the domain root in the /docs folder of the software package.

Nginx

Below is the example configuration to get your application running under Nginx with PHP-FPM.

If you have X-Cart installed into a web directory, see the web directory example configuration.

## X-Cart 5 nginx sample configuration
## Copy this file to your /etc/nginx directory
## and include it to your nginx.conf

#
# Replace placeholders:
# {{projects-dir}} - real full path of projects dir
#
# Example
#
# Projects dir installation path: /var/www/projects
# Some X-Cart store installation path (git clone root): /var/www/projects/xcart1
# Some other X-Cart store installation path (git clone root): /var/www/projects/xcart2
# Expected URL of first store: https://localhost/xcart1/src/public/
# Expected URL of second store: https://localhost/xcart2/src/public/
#

upstream fastcgi_xcart {
# use tcp connection
server 127.0.0.1:9000;
# or socket
# server unix:/var/run/php5-fpm.sock;
# server unix:/var/run/php/php7.0-fpm.sock;
}

server {
server_name xcart.test;

root {{projects-dir}};

index index.php;
charset UTF-8;

location ~ /service\.php/ {
try_files $uri $uri/ @handler2;
}

location @handler2 {
rewrite ^/(.*src)\/service\.php\/(.*)$ /$1/service.php?$query_string last;
}

location / {
try_files $uri $uri/ @handler;
}

location @handler {
rewrite ^/(.*src)\/(.*)$ /$1/index.php?$query_string last;
}

location ~ \.php(/|$) {
fastcgi_pass fastcgi_xcart;
fastcgi_split_path_info ^(.+\.php)(/.*)$;

fastcgi_read_timeout 300;

fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REDIRECT_STATUS 200;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;

fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT $realpath_root;

internal;
}

location ~ \.(jpg|jpeg|png|gif|woff|woff2|ttf)$ {
try_files $uri =404;
break;
}
}

Web directory

## X-Cart 5 nginx sample configuration
## Copy this file to your /etc/nginx directory
## and include it to your nginx.conf
##
## This configuration is prepared for the following server setup:
## Wordpress in the root of the domain
## XCart in web-dir

#
# Replace placeholders:
# {{web-dir}} - XCart web dir value
# {{root-full-path}} - real full path of host handler app (Wordpress)
# {{public-full-path}} - real full path of XCart public dir
#
# Example
#
# Host handler app path (Wordpress) : /var/www/http
# XCart installation path: /var/www/xcart
# Expected XCart URL: https://localhost/shop
#
# web-dir: /shop
# root-full-path: /var/www/http
# public-full-path: /var/www/xcart/public
#

upstream fastcgi_xcart {
# use tcp connection
server 127.0.0.1:9000;
# or socket
# server unix:/var/run/php5-fpm.sock;
# server unix:/var/run/php/php7.0-fpm.sock;
}

upstream fastcgi_other {
# use tcp connection
server 127.0.0.1:9000;
# or socket
# server unix:/var/run/php5-fpm.sock;
# server unix:/var/run/php/php7.0-fpm.sock;
}

# To use virtual web_dir with symfony routing and service-tool is is required to move web_dir from prefix to suffix
map $request_uri $real_request_uri {
~^{{web-dir}}(?:/service.php)([^?]*)(\?.*)?$ "/service.php{{web-dir}}$1";
~^{{web-dir}}(?:/\w+\.php)?([^?]*)(\?.*)?$ "{{web-dir}}$1";
default $request_uri;
}

# Determinate real file path
map $request_uri $real_file {
~^{{web-dir}}(?:/\w+\.php)?([^?]*)(\?.*)?$ $1;
default $request_uri;
}

server {
listen 80 default_server;
server_name xcart.test;
root {{root-full-path}};

index index.php;
charset UTF-8;

# Static files must not be processd trough fastcgi handler
location ~ {{web-dir}}(/.*\.(jpg|jpeg|png|gif|woff|woff2|ttf))$ {
alias {{public-full-path}};

try_files $1 =404;
break;
}

# Route index.php and service.php to the fastcgi handler
location ~ ^{{web-dir}}/(index|service)\.php {
alias {{public-full-path}};

try_files $real_file @handler;
}

# Route cleanurls to index.php
location ~ ^{{web-dir}}/ {
alias {{public-full-path}};

rewrite ^{{web-dir}}(.*)$ {{web-dir}}/index.php$1;
}

# XCart 5.5 handler (web-dir)
location @handler {
fastcgi_pass fastcgi_xcart;

fastcgi_split_path_info ^{{web-dir}}/(.+\.php)?(.*)$;

include fastcgi_params;

# Set real FS path
fastcgi_param SCRIPT_FILENAME {{public-full-path}}/$fastcgi_script_name;
fastcgi_param DOCUMENT_ROOT {{public-full-path}};

fastcgi_param REQUEST_URI {{web-dir}}/$fastcgi_script_name$fastcgi_path_info?$query_string;

# Prevents URIs that include the front controller. This will 404:
# http://domain.tld/index.php/some-path
# Remove the internal directive to allow URIs like this
internal;
}

# host handler (w/o web-dir)
location / {
try_files $uri $uri/ /index.php?$args;
}

location ~ \.php(/|$) {
include fastcgi_params;
fastcgi_intercept_errors on;
fastcgi_pass fastcgi_xcart;
#The following parameter can be also included in fastcgi_params file
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}
}

Please carefully check the above configuration sample and adapt it to your server environment.

You can find the sample of an Nginx server configuration for a store located in a subfolder but not in the domain root in the /docs folder of the software package.