Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Environment setup for developers

Describes how to set up your developer workstation to start building Commerce (SaaS) solutions.

🚧

Prerequisites

To successfully set up your Commerce (SaaS) developer environment, the following must be completed:

  • Possess knowledge and understanding of the Git technology and command line tools
  • Create a private GitHub repository and have access to edit collaborators
  • Optimizely has completed the provisioning of the Sandbox and Production Commerce (SaaS) instances.
  • Cloud developer workstation works on currently supported Microsoft Windows installations only. Linux and macOS are not supported.

Developer workstation setup process

Authorize Optimizely account to GitHub

📘

Note

This is only allowed for organizations. For personal accounts, Github only allows full access collaborators. To clone the Commerce (SaaS) repo, you need to create a shared service account, and the Commerce (SaaS) hosting team will add you to the group to access git clone https://github.com/InsiteSoftware/insite-commerce-cloud.git after you submit a ticket.

If you are new to Commerce (SaaS) and are not working on an active project, submit a support ticket requesting an invitation to the Commerce (SaaS) Git repository. Make sure to create a shared group Git account, as individual accounts are not allowed. For example, partnername-Optimizely not JonDoe-partner.

Only complete this section if you are connecting your repo to an environment hosted by Optimizely. This step allows build server access to the repository so support can pull your extensions into your environment. Do not complete this step if you are completing the developer training course.

  1. Go to the repo on github.
  2. Go to Settings > Collaborators & Teams.
  3. Enter insite-teamcity-build under Collaborators and click Add collaborator.
  4. Change permission for insite-teamcity-build to Read.

Clone insite-commerce-cloud repository

  1. Open git bash or command line.
  2. git clone https://github.com/InsiteSoftware/insite-commerce-cloud.git

Replace default remote origin

  1. Change directory to the cloned directory.
  2. git remote rm origin
  3. git remote add origin [YourRemoteGitPath]

For example, https://github.com/yourprofile/isccloud.git

Add upstream repository

Add the original upstream repository to receive any new updates deployed by Optimizely to the web project in the repository. This uses git tags to identify releases. Git pull specific releases to test specific versions locally against customizations (theme and extensions).

  1. git remote add upstream https://github.com/InsiteSoftware/insite-commerce-cloud.git
  2. git push --set-upstream origin master

Create a custom Classic Theme or Spire Blueprint

Classic CMS - Create a project theme using the PowerShell script provided. Multiple themes can be created in a single repository, however, themes cannot have the same name.

  1. Locate the local git repository in Windows Explorer and go to the /src folder.
  2. Open PowerShell and execute the ./createTheme.ps1 Powershell script. For example, ./createTheme.ps1 - themeName "YourCustomTheme".
  3. Open the Commerce.Web solution in Visual Studio and check that it has an Extension library, Commerce.Web project, and the custom Theme project.

Check Environment Versions – Use the steps in Upgrade Commerce (SaaS) to make sure the version generating the theme is in sync with the deployed version. This prevents merging a code version that is ahead of what you have deployed or are deploying.

📘

Note

The branch tags containing version name are prepended with lts or sts.

  • Lts currently uses .NET 4.8.
  • Sts currently uses .NET 4.8 and .NET 7. The .NET 7 framework is in beta.

See Long-Term Support overview for more information.

Configure Optimizely NuGet source in Visual Studio

NuGet packages are available on https://nuget.optimizely.com, which does not require authentication.

  1. Go to Visual Studio > Tools > Options > NuGet Package Manager > Package Sources.
  2. Click Add:
    1. Name – Commerce (SaaS)
    2. Source – https://nuget.optimizely.com/feed/packages.svc
  3. Restore packages.

Configure the local environment

Open Visual Studio and rebuild the solution.

For SQL, follow these steps:

  1. Create a database within SQL server
  2. Run ./database/Insite.Commerce.StartingDatabase.sql against the database.
  3. Optionally run ./database/Insite.Commerce.SampleData.sql against the database.
  4. Update ./src/InsiteCommerce.Web/config/connectionStrings.config so it can connect to your new database.
    connectionStrings.default.config is copied to connectionStrings.config during a build. If you skipped step 1, you can copy the file manually.

For IIS, follow these steps:

  1. Add a new site to IIS, pointing to ./src/InsiteCommerce.Web.
  2. Set up bindings:
    1. For simple setups, using a non-standard port like 8080 is fine. The site can then be accessed at http://localhost:8080.
    2. If dealing with multiple projects, it can help to have them setup with hostnames on port 80:
      projectA.local.com
      projectB.local.com
      This requires entries in c:\Windows\System32\drivers\etc\hosts:
      127.0.0.1 projectA.local.com
      127.0.0.1 projectB.local.com

      📘

      Note

      https is not required.

  3. Setup certificate:
    1. Run powershell {SDK Folder}\\tools\\generatePfx.ps1. This generates two files, insiteidentity.pfx and InsiteIdentityPassword.txt.
    2. Copy the generated insiteidentity.pfx to {Web Project Folder}/AppData/insiteidentity.pfx.
    3. Copy the password in InsiteIdentityPassword.txt into the IdentityServerCertificatePassword node in {Web Project Folder}/config/AppSettings.config

Once finished with either set of steps, log in to /admin with the following credentials:
user – admin
password – admin123

Finalize git branching

Create two local branches called sandbox and production, used by the corresponding deployments. Pushing to the remove server automatically creates the remote branch. Optimizely schedules production deployments. Pushing to the remote production branch does not automatically make the theme and server-side customizations go live. Sandbox deployments are automated, and any customizations refresh the insitesandbox.com domain within a few minutes of a git push to the remote sandbox branch.

  1. Open git bash or command line and open the install location.
  2. git branch sandbox.
  3. git branch production
  4. Verify the Commerce (SaaS) website loads in the browser on the local dev machine.

📘

Note

Git is a distributed version control system. Optimizely only supports pulling the Extensions code from GitHub, but you can use any version control system internally for your workflow. Attach the Github repo to your internal repo as a remote and push code to it.