- SAP Managed Tags
Working with SAP Commerce Cloud sometimes requires replicating a CCv2 database (e.g. from S1 or P1 - Production) locally for debugging, testing, or development purposes. In this article, we’ll walk through the process of copying the database from a CCv2 environment to your local setup, so you can develop with it on your work computer.
Prerequisites
Clean Up the Database
The process will involve SAP doing the database backup and the backup of media folders and sharing that with you. Therefore, you need to ensure your database and media folders are cleaned off any unnecessary data, otherwise you may have issues downloading big files or large amounts of small files, or you won't have enough space on your computer to restore and work with them.
You can use Quick Data Cleanup in SAP Commerce to do a one-time cleanup, but even better - create a set of cronjobs for a regular cleanup, so you can perform this copy of the database/media at any time (and also your database will be clean off garbage).
Open a Ticket with SAP
Open a ticket with SAP and ask them to create a backup of the database and the media folder, for the purpose of using them in your local development.
They will provide the database backup (or rather, export) as a bacpac file. This file, along with the media folders, will be uploaded to the Azure Blob Storage of the environment in question, so you can find them using Azure Storage Explorer. Please note that the media folders will be provided in expanded format (not archived).
Update Your Code Base
The database and the media you will be provided, correspond to the exact software version currently installed in the CCv2 environment you are copying. Therefore, make sure your local code base is at the exact branch, or even better - exact commit number, as what is in the CCv2 at the time of the database export.
Cloud Hot Folders
If your project is using cloud hot folders, then make sure you follow SAP Knowledge Base Article 2817992 - Cloud Hot Folder Extensions for SAP Commerce Cloud versions and download required extensions (and include them in your localextensions.xml), so you don't get build / runtime errors about these extensions missing, and you can continue working with cloud hot folders in your local.
Transparent Attribute Encryption (TAE) Settings
Some of the data in the database that SAP will provide - will be encrypted, specifically the attributes configured as encrypted (if you customized any), and most importantly - users' password hashes. You need to have your local Hybris use the same encryption key as in CCv2, otherwise you won't be able to log in to Backoffice or HAC - it won't be able to decrypt your password hash.
If the master password was not changed in CCv2, then you will probably be fine just not doing anything here. However, if it was changed (and it should've been changed according to the best practice recommendations from SAP), then do the following...
Download the encryption key from CCv2 (in the tab "Security Files") and copy it to your <HYBRIS_HOME>/config/security/ (create the "security" directory under "config" if it doesn't exist).
You also need to make sure the symmetric.key.* settings in your local are the same as in CCv2, for example:
symmetric.key.master.password=<password from this property in CCv2>
symmetric.key.file.1=<whatever the value in CCv2>
symmetric.key.file.default=<whatever the value in CCv2>
Build your code base with "ant clean all".
You can get more information about the TAE (including how to find the master password if it was not provided to you) in the following articles: SAP Commerce (Hybris): How to Update Master Password for Transparent Attribute Encryption (TAE) and SAP Commerce (Hybris): How to Rotate the Encryption Key.
Steps
Download the DB and Media Backups
Once SAP provides the DB and media backup into your Azure Blob, you will need to download them. You can use Azure Storage Explorer for the bacpac, but using it to download the media folders will probably be inefficient, since each folder will contain thousands of small files.
The more efficient way to copy the media folders is through AzCopy.
Generate the Shared Access Signature (SAS) by right clicking on the storage account and choosing "Get Shared Access Signature...":
Then use the following command to copy to your computer:
./azcopy copy "https://<account-name-from-screenshot>.blob.core.windows.net/<media-folder-name>?<SAS>" "~/Downloads" --recursive=true
For example:
./azcopy copy "https://k9rb7qvz24n6p3wxa5mf2eu.blob.core.windows.net/snap-20250330225246-sys-master-cronjob?sv=2023-01-03&ss=btqf&srt=sco&st=2025-04-02T14%3A53%3A26Z&se=2025-04-07T11%3A22%3A45Z&sp=rw&sig=B7y4kZ9MvLdqTeJPona7slGrKVpcFxU2stNgGAQRf99%3D " "~/Downloads/azcopy_darwin_arm64_10.27.1/new" --recursive=true
Do this with each media folder. Some media folders contain too many files (especially if proper cleanup wasn't performed before backing up), and if the process goes for too long or sometimes if it is interrupted manually, it can get stuck. In my case I wasn't able to connect to that storage account anymore at all. Apparently this issue is just related to your network, and if you connect to another network (e.g. use another WiFi or connect to your company's VPN), then this resolved it for me.
Place the Media Folders in the Correct Location
Once you've downloaded the media folders, you should place them inside your <HYBRIS_HOME>/data/media/sys_master/, but rename the folders e.g. "snap-20250330225246-sys-master-cronjob" --> "cronjob". Also, place the contents of the whole "snap-20250330225246-root" folder straight into <HYBRIS_HOME>/data/media/sys_master/.
Thus, your media folders are ready for use. Let's proceed to the database.
Restore the Database
The database restore process is quite different depending on which platform you use for development. Please see below what should be done on a Windows and on a Mac machine.
Database Steps on Windows
SAP currently provides a bacpac export of the database. You import it using SQL Server Management Studio.
To import a bacpac - in MSSMS, click "Databases" --> "Import Data-tier application":
Database Steps on a Mac
For a Mac, there is a difference between using an Intel or an Apple Silicon processor. Apparently, Intel processors support some of the needed software natively, however since I am on an Apple Silicon, I had to create a Windows VM (in Google Cloud), install Microsoft SQL Server Developer Edition and Microsoft SQL Management Tools, so I can restore the BACPAC and make a BAK out of it, and then restore the BAK onto my Mac, since I couldn't find a way to restore a BACPAC onto a Mac.
Create a Windows VM
I created a Compute Engine on Google Cloud with the following parameters:
- Operating System: Windows Server 2025 Datacenter - latest Windows Server to date, which supports SQL Server 2022 and future updates.
- Boot Disk Type: Balanced Persistent Disk - good balance of price and performance.
- Boot Disk Size: 100Gb:
- SQL Server Developer Edition itself requires ~20GB+.
- SQL Server Management Studio (SSMS) and related tools take several GBs.
- My BACPAC file was 700MB, but restoring it will expand (could be 5-10GB or more).
- Temporary storage for conversion to BAK will need additional space.
Then you need to make sure you don't forget to stop the instance when you don't need it. If you only have it up when needed, then it is pretty inexpensive - a couple dollars per hour, but if you forget to switch it off, then the money can add up to something you wouldn't want to pay.
After you created your Windows VM instance, you can RDP to the machine by downloading the RDP file from Google for this instance, and uploading it to your Remote Desktop emulator (I just use Windows Remote Desktop - it's free and has all the required features).
Actually, before RDP'ing for the first time, make sure to change the properties to redirect folders, so you can exchange files between your local Mac and your Windows VM, for example like this:
Once I created the VM, I installed Microsoft SQL Server Developer Edition and Microsoft SQL Management Tools on it, with the default settings.
Convert the BACPAC into a BAK
Copy the BACPAC to your Windows machine using the folder redirect that you set up earlier, then import the BACPAC in the way described in section "Database Steps on Windows".
Once you have the database restored on your VM, execute the backup to obtain the BAK file:
Copy the BAK file to your Mac machine through the folder redirect.
Install Microsoft SQL Server on Mac
Install MSSQL Server docker image on your Mac:
docker pull mcr.microsoft.com/mssql/server:2022-latest
If your Mac is on Apple Silicon, then you will need to run this docker image on emulation:
docker run -e "ACCEPT_EULA=Y" -e "MSSQL_SA_PASSWORD=PasswordYouSetUpForMSSQLServer" \
-p 1433:1433 --name sql_server_2022 \
--platform linux/amd64 \
-d mcr.microsoft.com/mssql/server:2022-latest
Upload the BAK to Docker
To copy your BAK file to docker - first create a folder on your docker:
docker exec -it sql_server_2022 bash
This will bring you the prompt like this:
mssql@61b91c0f7651:/$
Type:
mkdir -p /var/opt/mssql/backup
Then exit docker machine by typing exit.
Now actually copy the BAK to your docker, with a command like this:
docker cp ~/Downloads/CCv2ExportedDB.bak sql_server_2022:/var/opt/mssql/backup/CCv2ExportedDB.bak
Install sqlcmd tool
In order to restore the BAK onto your Mac MSSQL Server, you will need the "sqlcmd" tool. To install it, execute the following commands on your Mac:
brew tap microsoft/mssql-release https://github.com/Microsoft/homebrew-mssql-release
brew update
brew install msodbcsql mssql-tools
To verify that "sqlcmd" is working, execute the following:
sqlcmd "-?"
You will get the help message. (Note that just typing "sqlcmd -?" will not work, you need to have the dash and the question mark in double quotes.)
Now connect to your Mac MSSQL using sqlcmd:
sqlcmd -S 127.0.0.1 -U SA -P YourSAPassword
If you successfully connected, then you will see the prompt:
1>
Restore the BAK onto your Mac's MSSQL
Type the command below to show logical partitions for data and log:
RESTORE FILELISTONLY
FROM DISK = '/var/opt/mssql/backup/CCv2ExportedDB.bak';
GO
Then use the logical partitions in the restore command, like this:
RESTORE DATABASE CCv2ExportedDB
FROM DISK = '/var/opt/mssql/backup/CCv2ExportedDB.bak'
WITH
MOVE 'CCv2ExportedDB_Data' TO '/var/opt/mssql/data/CCv2ExportedDB.mdf',
MOVE 'CCv2ExportedDB_Log' TO '/var/opt/mssql/data/CCv2ExportedDB_log.ldf',
RECOVERY, REPLACE;
GO
In the above command, substitute CCv2ExportedDB_Data and CCv2ExportedDB_Log with the names you obtained from the previous command "RESTORE FILELISTONLY".
This will restore the database from the BAK.
You may get errors like this:
Msg 12824, Level 16, State 1, Server 92171932bc6a, Line 1
The sp_configure value 'contained database authentication' must be set to 1 in order to restore a contained database. You may need to use RECONFIGURE to set the value_in_use.
Msg 3013, Level 16, State 1, Server 92171932bc6a, Line 1
RESTORE DATABASE is terminating abnormally.
To fix those, run the following:
1> EXEC sp_configure 'show advanced options', 1;
2> RECONFIGURE;
3> GO
...and:
1> EXEC sp_configure 'contained database authentication', 1;
2> RECONFIGURE;
3> GO
To verify restore was successful, see if your new database now exists:
SELECT name FROM sys.databases;
GO
Then switch to the database and list tables:
USE CovercraftDB;
GO
SELECT name FROM sys.tables;
GO
Optionally, you can select something from some table, for example:
SELECT COUNT(*) FROM products;
GO
Configure Local Hybris to Point to Local MSSQL
Point your local environment to the CCv2 database you just restored - update your local.properties:
db.url=jdbc:sqlserver://localhost:1433;database=CCv2ExportedDB;loginTimeout=4
db.driver=com.microsoft.sqlserver.jdbc.SQLServerDriver
db.username=SA
db.password=YourSAPassword
db.type.system.name=ts20250326T134449
(Of course you can configure a user other than SA for this database if you like.)
Please note you should include the property "db.type.system.name" and set it to the same value as CCv2. CCv2 names the new type system on every system update, so we need to make sure we work with the same one.
Update Media Locations
Now that you can run Hybris, you will probably see lots of errors in your log about media not found or media folder incorrect.
There is an important difference between how medias work in CCv2 and in local. CCv2 uses cloud media storage strategy, and local will use local media storage strategy. This is already correctly configured in your local.properties, however there is a catch - the cloud media storage strategy places medias in media folders, but doesn't prefix the locations with the media folder name, and the local media storage strategy expects the locations to be prefixed with the media folder name. For example, image "logo.gif" is in media folder "images", and in the cloud its location will be something like "h27/h01/logo.gif", but in local it is expected to be "images/h27/h01/logo.gif". Moreover, there is media location hash that should be recalculated based on the new media location.
I wrote a script that would process all the media items and reassign their location field so it is prefixed with their folder name, and recalculate the hash. You can find the script here: https://github.com/olsido/hybris-utils/tree/develop/HybrisUpdateMediaFolders. It can take awhile to convert all the media like this, but it is worth it - you will not see any more media errors in the log, and you will see beautiful pictures in your local storefront!
Solr Security
Solr console is accessible without a password in CCv2. In local, by default, your Solr server will require username and password solrserver / server123. You will need to update the database you just copied with that configuration data:
$serverConfigName=Default
INSERT_UPDATE SolrServerConfig;name[unique=true];username;password;indexingUsername;indexingPassword;solrQueryMethod(code)
;$serverConfigName;solrserver;server123;solrserver;server123;POST
Once you rebuild and restart Hybris, log in to Solr console, unload backoffice core, then do a full index on Backoffice product indexed type.
Then you can do a full index on your product catalog, also unload the core before this if needed.
Pretty URLs
On some projects, the front-end accesses the images and other media items using "pretty URLs". Make sure your media.legacy.prettyURL property is set to the same value as in CCv2, otherwise you won't be able to see images on the storefront.
You're Done!
After you make all the changes to your local.properties, make sure to rebuild your system.
You don't have to "update system", since the database you've copied is already updated to the commit number of your code.
It would be good if you have the patching framework in use on your project, so that after the copy-over of the CCv2 database, it automatically updates with any changes in subsequent releases.
By following the steps in this article, you can copy the database and media from CCv2 into your local and have your local environment be exactly like CCv2 testing or production environment, which is beneficial for development and troubleshooting.
