Skip to content

Getting started

System requirements

Amarant version PHP PostgreSQL Redis Elasticsearch Varnish Node
latest 8.4 16.3 7.2 8.11 7.6 20

PHP extensions:

  • bcmath
  • ctype
  • curl
  • dom
  • ds
  • gd
  • iconv
  • intl
  • json
  • libxml
  • openssl
  • pcntl
  • pdo
  • pdo_pgsql
  • simplexml
  • sodium
  • opcache

Misc:

  • rsync (must be present and executable on the system path as it's used by the Composer plugin)

Project initialization

To create a new e-commerce project with composer, use the following project template:

composer create-project amarant2/project-template --repository-url=https://repo.amarant-commerce.com

If you're building a custom application, create a new framework project instead:

composer create-project amarant2/framework-project-template --repository-url=https://repo.amarant-commerce.com

Project structure

├── bin
│   └── ama
├── code
├── design
├── etc
├── generated
├── private
├── tests
├── var
├── web
│   └── area
│       └── backend
│           └── static
│       └── frontend
│           └── static
└── .env
└── .env.test
└── jsconfig.json
└── tsconfig.json
└── vite.config.backend.amarant_hadron.mts
└── vite.config.frontend.amarant_lux.mts
bin/ama The Amarant CLI.
Use it to run various commands defined in application modules.
code Custom application code
design Custom themes
etc Module and theme lists
generated Generated application files
private Private storage directory, used for keys and certificates
tests Bootstrap code for tests
var Logs, reports and temporary files
web/area Backend and frontend application entry points and generated static files
.env Environment variables with factory values.

Create .env.local file to override factory values or to add new variables.

Never change the factory .env file because it might be updated during module update or reinstall.
.env.test Environment variables loaded when running tests. You can customize this file according to your application needs.
jsonfig/tsconfig.json Generated Javascript/Typescript configuration used by the web build process
vite.config.* Vite build configuration files generated by the web build process

Override factory configuration

Create .env.local file in the project root directory.

Configure database

.env.local
AMA_DB_NAME=your_database_name
AMA_DB_DSN=pgsql:host=your_database_host;port=your_database_port;dbname=your_database_name;user=your_database_user;password=your_database_password

AMA_CLI_DB_NAME=your_database_name
AMA_CLI_DB_DSN=pgsql:host=your_database_host;port=your_database_port;dbname=your_database_name;user=your_database_user;password=your_database_password

Replace the placeholder values with the ones applicable for your database.

Note

The CLI database name and its DSN will be used only in the console application (bin/ama), scheduled jobs and messaging workers. A usage example might be; using a direct connection to Postgres in CLI while using a pool like pgbouncer or similar for the http applications (frontend and backend entrypoints).

Change the frontend and backend hosts and their subdomains (Optional)

.env.local
AMA_MERCHANT_BACKEND_HOST=amarant2.local
AMA_MERCHANT_FRONTEND_HOST=amarant2.local
AMA_MERCHANT_PUBLIC_ID=merchant
AMA_MERCHANT_PRIVATE_ID=backend

The public id is the default subdomain at which the frontend store can be reached at, on the frontend host and private id is the default subdomain at which the back office can be reached at, on the backend host.

This means that by using the configuration above, we can access the frontend store under merchant.amarant2.local and the back office under backend.amarant2.local.

When channel domains are defined and set as active, they are used to match a particular channel using the host, at request time. This is only applicable for the frontend store, not the back office, which is always reached at private-id.backend-host.

Configure Redis

If Redis is not running locally or not on its default port, you need to override the following:

.env.local
REDIS_URI=tcp://your_redis_host:your_redis_port?database=1
IDENTITY_STORAGE_REDIS_URI=tcp://your_redis_host:your_redis_port?database=2
MESSAGING_REDIS_URI=tcp://your_redis_host:your_redis_port?database=3
MESSAGING_STATE_REDIS_URI=tcp://your_redis_host:your_redis_port?database=4

Replace the placeholder values with the ones applicable to your Redis instance.

Note

Redis keys are automatically prefixed with the merchant name (public id).

Configure Elasticsearch

If Elasticsearch is not running locally or not on its default port, you need to override the following:

.env.local
AMA_CONFIG_SYSTEM_SEARCH_ELASTICSEARCH_HOST=your_elastic_search_host
AMA_CONFIG_SYSTEM_SEARCH_ELASTICSEARCH_PORT=your_elastic_search_port

Replace the placeholder values with the ones applicable to your Elasticsearch instance.

Note

Elasticsearch indexes are automatically prefixed with the merchant name (public id).

Optionally, you can add additional prefix and suffix to index names, by overriding these values:

.env.local
ELASTIC_SEARCH_GLOBAL_INDEX_PREFIX=your_prefix
ELASTIC_SEARCH_GLOBAL_INDEX_SUFFIX=your_suffix

Configure frontend store security

.env.local
JWT_KEYPAIR_PASSPHRASE=changeme
CSRF_TOKEN_SECRET=changeme

Set a passphrase for the JWT keypair and a secret for the CSRF token storage.

Configure back office security

.env.local
BACKEND_API_KEY_SECRET=changeme
BACKEND_CSRF_TOKEN_SECRET=changeme
BACKEND_JWT_KEYPAIR_PASSPHRASE=changeme

Set API key and CSRF token secrets. Set a passphrase for the JWT keypair.

Configure configuration encryption

.env.local
AMA_CONFIG_SECURITY_ENCRYPTION_KEY=your_encryption_key
AMA_CONFIG_SECURITY_ENCRYPTION_NONCE=your_nonce

To generate the key and nonce, use the following command in the Amarant CLI:

php bin/ama security:encryption-keys:generate

Replace the placeholders with the generated values that are shown.

Docker setup

Project template includes Docker files for development.

Build the base image:

docker build --no-cache --pull=false -f docker/common/amarant/base/dev/Dockerfile -t amarant/base:latest .

Next, copy .env.docker file to .env.docker.local and make port adjustments.

.env.docker.local
AMA_FRONTEND_PORT_MAPPING=8081:80
AMA_BACKEND_PORT_MAPPING=8082:80

Start the application and services:

docker compose --env-file=.env --env-file=.env.docker.local up -d --wait

You can now do a proxy pass from your local Apache, Nginx or other server to frontend and backend ports to access the shop frontend and the backoffice.

Additionally, ports 5173 and 5174 will be available on localhost for Vite.

Installation

Enable modules and themes (Optional)

To enable modules, add their module file to modules.php. Otherwise, to disable them, remove them from the file.

etc/modules.php
<?php

return [
    \Amarant\Framework\Module::class,
    \Amarant\Store\Module::class,
    \Amarant\Product\Module::class,
    \Amarant\Sales\Module::class,
    \Amarant\Ui\Module::class,
    \Amarant\Backoffice\Module::class,
    \Amarant\Cms\Module::class,
    // add a module
    \Vendor\ModuleName\Module::class,
];

To enable themes, add their theme file to themes.php. Otherwise, to disable them, remove them from the file.

etc/themes.php
<?php

return [
    \Amarant\Lux\Theme::class,
    \Amarant\Hadron\Theme::class,
    // add a theme
    \Vendor\ThemeName\Theme::class,
];

Generate JWT keypair

php bin/ama security:jwt:generate-key-pair

The generated keys will be stored inside the private directory under the project root.

Execute database migrations

php bin/ama db:migrations:migrate -vvv

Execute module updates

php bin/ama module:update -vvv

Clear caches

php bin/ama cache:clear -vvv

Clear cached files

rm -rf var/cache/*

Post-installation

Install product sample data (Optional)

php bin/ama product:samples:sync-async -vvv

Crontab

Add an entry to your crontab to enable scheduled jobs.

* * * * * /usr/bin/php /var/www/html/bin/ama schedule:run 2>&1 >> /var/www/html/var/log/cron.log

For local development, you can skip this part if you want to run jobs and workers manually.

Note

The paths mentioned above are just an example. Use the correct PHP executable and project path, accordingly.

Create a back office user

php bin/ama user:account:add your_username your_email

Replace the placeholders with your actual username and email.

Warning

Store this password safely. You can't retrieve this password later as it is stored as a hash in the database.

Presentation layer initialization

Install dependencies

npm install

Use a different frontend store theme

Add the following line to your .env.local file.

.env.local
AMA_CONFIG_VIEW_FRONTEND_THEME=Vendor_VendorTheme

Change the value to the desired theme name.
This will set the theme as default in the default scope.

Later on, you can change the theme for a particular channel in the back office.

Note

By default, the frontend store uses the "Lux" theme while the back office uses "Hadron" theme.
Both themes come preinstalled.

Build static content

php bin/ama view:theme:build frontend --build-mode=build
php bin/ama view:theme:build backend --build-mode=build

This will build and deploy production version of CSS, JS and static files into the "web/area/*/static" directories.

Command line options

--theme-name

Optionally specify a theme you want to build/develop. Default theme for an area will be used if no theme name is specified.

Default: Current area theme

--inherit-entry-points

Inherit entrypoints (theme.js/theme.ts, theme.css/theme.scss) from all parent themes.

Default: true

Use the application

To use production static content that was just built, the application must be in production mode. To do this, add the following line to you .env.local file.

.env.local
APP_MODE=prod

If you would like to stay in development mode, for the frontend area use the following command:

php bin/ama view:theme:build frontend

For the backend area (back office) use the following command:

php bin/ama view:theme:build backend

This command will run Vite in development mode and automatically rebuild files on change.

Application setup is now complete.

Developer toolbar

To enable the developer toolbar, set the following environment variables in .env.local file.

.env.local
APP_DEBUG_DEVELOPER_TOOLBAR=1
APP_PROFILER_ENABLED=1

This will allow you to observe various information about the current request.

Developer toolbar

Click on the button to the left to view details about database queries, layouts, blocks, events and more.

Developer toolbar