Create code packages

4 min

Code package naming convention

The first step to using the API is to bundle your web application into a code package. Use the following conventions when you name a code package (a package containing Web App binaries, configuration, and so on).

<app name>.<package type>.app.<version>.nupkg or <app name>.<package type>.app.<version>.zip

app name – Optional. Must not contain spaces or special characters.

package types – cms (primary Web App).

version – You can specify it differently, using a "date format" or a version number.

Example code package names

cms.app.1.0.0.nupkg

cms.app.1.0.0.zip

customer.cms.app.1.0.0.nupkg

customer.cms.app.1.0.0.zip

(In this example, customer is the app name.)

Code package content

The package should contain the Web App-related files.

Only folders and files related to the code are allowed (such as wwwroot, binaries, and appsettings.json) and a metadata file (optional) that follows the package name.

Sample folder structure

myapp.cms.app.1.0.0.nupkg
  wwwroot
  appsettings.json
  appsettings.Integration.json
  appsettings.Preproduction.json
  appsettings.Production.json
  dxpPlatformSettings.json
  myapp.dll
  ......
  myapp.cms.app.nuspec (optional)

Environment configurations need to be a part of the code package.

You can download an Optimizely Content Management System (CMS) sample site (Alloy) package example here: alloy-linux.cms.app.20241210.nupkg

Create a code package

You can create a package by deploying to a folder and zipping this folder: dotnet publish ~/projects/myapp/myapp.csproj

You can zip this folder (SitePackageContent in the example) as cms.app.1.0.0.nupkg to make it a deployment package that you can use in DXP.

Platform settings file

To support making some additional configurations, you can include dxpPlatformSettings.json, which should follow the JSON schema below.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "The schema file that should be used for validation",
      "enum": [
        "https://schema.episerver.net/paasportal/2022-03-24/platformschema.json"
      ]
    },
    "entrypoint": {
      "type": "string",
      "description": "Manually specified entrypoint to use in the docker configuration"
    },
    "platformPackages": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "description": "Additional packages that should be installed",
          "properties": {
            "name": {
              "type": "string",
              "description": "Name of the package",
              "enum": [
                "NodeJs"
              ]
            },
            "version": {
              "type": "integer",
              "description": "Version of the package that should be installed"
            }
          },
          "required": [
            "name",
            "version"
          ]
        }
      ]
    }
  },
  "required": [
    "$schema"
  ]
}

This code lets you explicitly specify what entry point to use for your application if it contains multiple assemblies and you are worried the wrong one might be used.

This also allows for installing additional platform packages that extend the image beyond what is normally allowed in a code package, such as installing a newer NodeJs version.