What are the different ways to deploy DAML applications and should we be using all of them?

Questions
,
1

You can deploy a dar file to a ledger using the following approaches:

  1. sbt "run --port 6865 --role provision,time,ledger,explorer path/to/my.dar"

  2. sbt "run --port 6865 --role provision,time,ledger,explorer"
    daml deploy --host localhost --port 6865

  3. sbt "run --port 6865 --role provision,time,ledger,explorer"
    daml ledger upload-dar --host localhost --port 6865 path/to/my.dar

So what do each of these do and is there a recommended/best way to write docs around these?

2 Likes
2

Great question! Let me go through the options:

  1. This is a ledger-specific thing. Presumably you are using daml-on-fabric here (although you didn’t mention it). The DAML sandbox has something similar where you can pass in a DAR on the command line when starting it. This is convenient when you just want to test something out but as mentioned it is ledger-specific. There is no guarantee that this is possible at all and even if it is possible, the syntax can very from ledger to ledger. Furthermore, it does not help you if you already have a running ledger.

  2. I’ll explain this before 2 since it is the simpler command. daml ledger upload-dar uses the Ledger API to upload a package. Since the ledger API is supported by any ledger, this works against any ledger contrary to 1. It also works against an already running ledger so you do not have to restart your ledger every time you want to upload a new DAR. If you do not pass in the path to a DAR, it will build the DAR for the project you are currently in using daml build and upload that. You can also omit host and port and they will be read from daml.yaml. If you specify host, port and the DAR you can run this command without being inside of a project which is sometimes convenient.

  3. Now on to daml deploy. This is an extension of daml ledger upload-dar. It will first look at your daml.yaml file and read the parties specified under the parties field. For each party, it will then check if there already exists a party with the given display name (it does not check the party id). If it does not yet exist, it will allocate the party with the display name specified in your daml.yaml and the party id hint set to the same name.
    Once it has allocated the parties it uploads the DAR just like daml ledger upload-dar. So daml deploy is just a wrapper around daml build, daml ledger allocate-parties and daml ledger upload-dar. If you want to do all 3, use daml deploy. If not, then use daml ledger upload-dar separately.

5 Likes
3

Great answer @cocreature , very comprehensive!

I’ve seen a case on an older version of the SDK when trying to use daml deploy, where it fails with an error saying “not implemented”. I could use daml upload-dar without problems though, and created the parties using the navigator console.

Is it correct to assume that daml deploy was added to the SDK later ? Otherwise, is the availability of daml upload-dar or deploy commands really not dependent on the underlying ledger implementation?

1 Like
4

IIRC they were added in the same version but it’s been a while. All SDKs from the last 6 months should definitely have both. If you see the error again, please report a bug!

1 Like