Deployment¶
This section provides detailed instructions on how to deploy the new Virto Commerce Frontend Application across various environments. The deployment options available are:
Deployment on Virto Cloud¶
Virto Cloud natively supports the new architecture. Use the following methods to deploy in Virto Cloud:
Through configuration file¶
To deploy through configuration files:
- Disable the storefront application by removing it from the configuration.
- Add a reference to the Virto Commerce Frontend Application 2.x.
- Enable the routes section. The table below shows the mapping of paths to platform routes. The platform routes handle all requests related to the SPA's core functionality, such as authentication, authorization, file management, and data querying.
Path | Description |
---|---|
/xapi | A custom API endpoint for interacting with the SPA's backend services. |
/files | A path for uploading and downloading files from the SPA's storage. |
/connect/token | A path for requesting and refreshing access tokens for the SPA's users. |
/graphql | A path for executing GraphQL queries and mutations on the SPA's data. |
/revoke/token | A path for revoking access tokens for the SPA's users. |
/api/files | An alternative path for accessing the SPA's file management service. |
These routes are integral to ensuring that the SPA operates smoothly and securely, handling everything from user authentication to complex data interactions.
The appropriate snippet of the environments.yml file is as follows:
storefront:
enabled: false
imageRepository: virtopaasregistrymain.azurecr.io/vcptcore/storefront
servicePlan: S1
imageTag: 6.37.0-master-628b3528
config:
DOTNET_USE_POLLING_FILE_WATCHER: true
ASPNETCORE_FORWARDEDHEADERS_ENABLED: true
CookieAuthenticationOptions__ExpireTimeSpan: 12:00:00
SnapshotCollectorConfiguration__IsEnabled: false
Swagger__UI__Enable: true
VirtoCommerce__DefaultStore: B2B-store
VirtoCommerce__Endpoint__Password: store
themes:
B2B-store: https://vc3prerelease.blob.core.windows.net/packages/b2b-webservice.zip
ingress: {}
customApps:
app1:
enabled: false
app2:
enabled: false
routes:
- host: vcptcore-dev-storefront.govirto.com
root: B2B-store
paths:
- path: /xapi
route: platform
- path: /files
route: platform
- path: /connect/token
route: platform
- path: /graphql
route: platform
- path: /revoke/token
route: platform
- path: /api/files
route: platform
protectedParameters:
- platform.image.tag
- storefront.image.tag
#- themes.B2B-store
#- custom.app1.image.tag
Through Virto Cloud portal [In Progress]¶
The detailed instructions will be provided soon.
Deployment on Azure¶
To deploy the Frontend Application on Azure:
-
Create all Azure resources using the Azure button:
-
Fill in the required values on the Custom deployment page and create Azure resources:
-
After successful deployment, open the Platform and perform initial setup, installing sample data if necessary.
- Change the default password for the admin user.
-
Set the store URL (Stores → Your store → Store URL) in the Platform in the form of
http://x.x.x.x/
: -
Use the Azure Application Gateway IP address to access the Frontend part of Virtocommerce solutions.
Your Frontend App has now been successfully deployed on Azure.
Common deployment issues¶
During the deployment process, various issues can arise that require attention, including:
Azure template validation issue¶
An Azure template validation error may occur if a resource with the selected name already exists. The error message typically indicates that the name must be modified before proceeding.
This issue can arise because the template uses the App Service Name
parameter as a name for other Azure resources, potentially leading to conflicts.
Password issue¶
Errors may occur if the password entered in the Sql Administrator Password
field does not meet complexity requirements.
To resolve this, the template must be redeployed with a new, compliant password.
Azure infrastructure issue¶
The error occurs during the deployment process and has a self-explanatory description.
The problem is usually temporary and cannot be solved by the user. The workaround is to use a new resource group for the deployment.
Deployment on local machine¶
Deploying on a local machine includes:
Prerequisites¶
Before installing the Frontend Application:
- Install Platform latest version or connect to an instance of the platform that is already set up and running on a cloud service.
- Install Experience API/xAPI modules:
-
Install the following modules for development (but not in production. This will be changed soon):
-
Install Node.js v22 (22.10.0 or higher).
- Enable corepack (run as administrator on Windows):
If you have installed yarn
globally, uninstall it:
-
via
npm
: -
or through your operation system installation tools:
- Control Panel, Chocolatey, or Scoop on Windows.
- Launchpad, Finder, Homebrew, or MacPorts on macOS.
- Native package manager such as apt on Linux.
Frontend Application deployment¶
To deploy the Frontend Application on a local machine:
-
Clone the repository:
-
Check
yarn
version. It should be 4.1.0 or higher (not 1.XX.): -
Install dependencies:
-
Build and run with hot reload for development:
- Add new .env.local file.
-
Copy APP_BACKEND_URL from the .env file and set its value to the correct endpoint to Virto Commerce Platform:
-
Run
yarn dev
oryarn dev-expose
: -
Follow the link provided in the terminal.
Your Frontend Application is now running successfully.
Build options¶
Choose the appropriate build command based on your needs:
-
Build for production with validation and minification:
-
Build in development mode:
-
Build in development mode with change tracking:
Types generation¶
To keep your project aligned with the GraphQL server, you need to generate the necessary types by running the following command:
This command generates the types.ts file for the Core App and independent modules. Even if independent modules are not installed on the platform, the types can still be generated safely.
Dependency analysis¶
The following sections guide you through analyzing bundle sizes and visualizing the dependency graph.
Bundle size analysis¶
To optimize your application, it’s important to understand the size of various JavaScript chunks like vendor.js and index.js. Run the following command to analyze bundle sizes:
The results will be saved in the artifacts folder, providing you with a clear overview of your bundle sizes.
Visualize dependency graph¶
Use the command below to generate a dependency graph:
Note
This command requires specific parameters to run successfully. For example:
The generated graph will be saved in the artifacts folder for your review.
Localization¶
Below are the steps to check and fix missing locale keys.
Check for missing locale keys¶
To ensure that all locale files have consistent keys across different languages and avoid missing translations, run:
The script outputs warnings for any missing keys in the locale files. Review these warnings to ensure all necessary translations are present. This check is also integrated into the CI pipeline to automate the validation process.
Fix missing locales¶
To automatically fix missing translations in the locale files using AI translation, run.
This command analyzes all locale files, identifies missing keys, translates the missing content from the source language to the target language, and updates the locale files accordingly.
Note
This command requires the APP_GEMINI_API_KEY
environment variable to be set. You can obtain this API key from the Google AI Studio website.
Warning
This is an experimental feature and may not work as expected.
Troubleshooting¶
If you encounter an error such as dot command not found
on Windows, it's likely due to a missing Graphviz installation. Ensure that Graphviz is installed on your system to resolve this issue.