Installation

Before you start

• Unpack the distribution archive to your web server. Important: The server document root must be set to the folder <XCart>/public, not the (<XCart>) root folder. For more info on configuring the server, see:

  Server Setup

• Specify the environment settings. To do this, you will first need to create a file <XCart>/.env.local (or copy the file <XCart>/.env to <XCart>/.env.local). Next, you will need to specify the variable values in that file as provided below.

Database connection. If a socket is being used, specify localhost as the host in DATABASE_URL; otherwise, specify the ip address 127.0.0.1

# Format described at https://www.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connecting-using-a-url
# IMPORTANT: You MUST configure your server version, either here or in config/packages/doctrine.yaml
#
# IMPORTANT: You MUST NOT specify driver in DATABASE_URL because we use a custom driver
DATABASE_URL="//db_user:db_password@127.0.0.1:3306/xc5?serverVersion=5.7"
DATABASE_UNIX_SOCKET=
DATABASE_CHARSET=utf8
DATABASE_DEFAULT_TABLE_PREFIX="xlite"

# If the Mysql server is started with the "require_secure_transport=ON" flag,
# then these parameters must contain the paths to the certificate files
DATABASE_SSL_CA_CERT=
DATABASE_SSL_CLIENT_CERT=
DATABASE_SSL_CLIENT_KEY=

Domain

#
# X-Cart 5 HTTP & HTTPS host, web directory where cart installed and allowed domains
#
# NOTE:
# You should put here hostname ONLY without http:// or https:// prefixes.
# Do not put slashes after the hostname.
# Web dir is the directory in the URL, not the filesystem path.
# Web dir must start with slash and have no slash at the end.
# The only exception is when you configure for the root of the site,
# in which case you should leave the option empty.
# Domains should be listed separated by commas.
#
# WARNING: Do not set the "$" sign before the parameter names!
#
# EXAMPLE 1:
#  XCART_HOST_DETAILS_HTTP_HOST=www.yourhost.com
#  XCART_HOST_DETAILS_HTTPS_HOST=www.securedirectories.com/yourhost.com
#  XCART_HOST_DETAILS_WEB_DIR=/shop
#  XCART_HOST_DETAILS_DOMAINS=www.yourhost2.com,yourhost3.com
#
# will result in the following URLs:
#
#  http://www.yourhost.com/shop
#  https://www.securedirectories.com/yourhost.com/shop
#
# EXAMPLE 2:
#  XCART_HOST_DETAILS_HTTP_HOST=www.yourhost.com
#  XCART_HOST_DETAILS_HTTPS_HOST=www.yourhost.com
#  XCART_HOST_DETAILS_WEB_DIR=
#
# will result in the following URLs:
#
#  http://www.yourhost.com
#  https://www.yourhost.com
XCART_HOST_DETAILS_HTTP_HOST=
XCART_HOST_DETAILS_HTTPS_HOST=
XCART_HOST_DETAILS_ADMIN_HOST=

# Web dir is the directory in the URL, not the filesystem path.
# Web dir must start with slash and have no slash at the end.
# The only exception is when you configure for the root of the site,
# in which case you should leave the option empty.
XCART_HOST_DETAILS_WEB_DIR=
XCART_HOST_DETAILS_DOMAINS=
XCART_HOST_DETAILS_ADMIN_SELF=admin/
XCART_HOST_DETAILS_CART_SELF=/
XCART_HOST_DETAILS_FORCE_HTTPS=

Redis

X-Cart requires configuring two separate Redis instances. You need to specify the following environment variables:

###> Redis ###
# Main Redis (for sessions and locks)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DSN=redis://localhost:6379

# Additional Redis (for cache)
REDIS_EXTRA_HOST=localhost
REDIS_EXTRA_PORT=6380
REDIS_EXTRA_DSN=redis://localhost:6380
###< Redis ###

###> symfony/lock ###
# For Redis-based locks (recommended for most cases)
LOCK_DSN=redis://localhost:6379

# Alternative options for specific requirements:
# LOCK_DSN=semaphore  # Use semaphores (enhanced speed and accuracy)
# LOCK_DSN=flock:///path/to/locks  # Use file-based locks
###< symfony/lock ###

Required variables:

• REDIS_HOST, REDIS_PORT - used to connect to main Redis (sessions)
• REDIS_EXTRA_DSN - used to connect to additional Redis (caching)
• LOCK_DSN - DSN for the lock system. By default uses Redis (redis://localhost:6379), but can be configured to use semaphores (semaphore) or file-based locks (flock://) depending on performance requirements

Variables for consistency:

• REDIS_DSN - used for compatibility, typically matches LOCK_DSN when using Redis for locks
• REDIS_EXTRA_HOST, REDIS_EXTRA_PORT - DSN format alternatives for additional Redis

Important! Both Redis servers must be running and accessible before installing X-Cart. Detailed information about Redis configuration is available in the Configuration section.

The rest of the settings do not have to be changed for the purpose of X-Cart installation but you may need to check and adjust them later to ensure that everything works properly.

Installation

The installation process can be launched from the command line. For that, issue the following command:

./bin/install.sh [-a admin-credentials]

Additionally, it is possible to use the key "-a" to specify the administrator login (email) and password in the format {login/email}:{password}

For example:

./bin/install.sh -a some.email@domain.com:s3cre4pa55w0rd

Provided that the server has been configured properly, after the installation process has been completed, your X-Cart store will become available at the domain specified.

The store's Admin area will be available at the address domain.com/admin/ ("domain.com" needs to be replaced by your actual domain).