Fix "Getting Started" documentation

[LeifLazar]

I've been trying to setup Synapse locally, using Docker, on Windows 11 and ran into a couple of issues while following the instructions from the repo readme file (Getting Started section).

🟡 - Needs documentation changes
🟢 - Needs to be added to documentation
🔴 - Might need code/configuration changes

🟡 Step 3 needs to be updated from:
docker-compose build
to:
docker-compose -f docker-compose.build.yml build

🟡 Step 4 needs to be updated from:
docker-compose up
to:
docker-compose -f docker-compose.build.yml up

🟢 Should add a mention that we need to pull a runner image to be able to run a workflow. For example:
docker pull ghcr.io/serverlessworkflow/synapse/runner:1.0.0-alpha5
🔴 I had to trick Synapse into running this alpha5 image by running this command:
docker tag ghcr.io/serverlessworkflow/synapse/runner:1.0.0-alpha5 ghcr.io/serverlessworkflow/synapse/runner:1.0.0
What did I miss here?

🔴 I had to modify the docker-compose.build.yml file in two ways.
The garnet tag from:

garnet:
  image: ghcr.io/microsoft/garnet
  volumes:
    - garnet_data:/data

to:

garnet:
  image: ghcr.io/microsoft/garnet
  entrypoint:
    - /app/GarnetServer
    - --lua
  volumes:
    - garnet_data:/data

and in the operator.environment section I had to add this:
SYNAPSE_RUNTIME_DOCKER_SECRETS_DIRECTORY: C:\Users\[MY_USER]\.synapse
This is clearly not cross-platform friendly but we need to either fix it or document it properly.

🟡 The example workflow definition needs to be updated from:

# greeter.yaml
document:
  dsl: '1.0.0'
  name: greeter
  namespace: default
  version: '0.1.0'
do:
  greet:
    set:
      greetings: '${ "Hello \(.user.firstName) \(.user.lastName)!" }'

to:

# greeter.yaml
document:
  dsl: "1.0.0-alpha5"
  name: greeter
  namespace: default
  version: "0.1.0"
do:
  - greet:
      set:
        greetings: ${ "Hello \(.user.firstName) \(.user.lastName)!" }

By this, I mean that we need to make it more clear that the version can't just be copy-pasted (or actually solve that problem) and that the formatting of the do...greet is wrong.

🟡 We also need to mention that the version of the dsl property should match the version of the runner image that was pulled. Or at least that's what I thought. Am I wrong?

I can open a p.r. for this once the discussion is settled.

[cdavernas]

First of all, many thanks for reporting the issue(s)!

🟡 Step 3 needs to be updated from:
docker-compose build
to:
docker-compose -f docker-compose.build.yml build

🟡 Step 4 needs to be updated from:
docker-compose up
to:
docker-compose -f docker-compose.build.yml up

Actually, suggested fixes would be but temporary, and would "force" user to build locally. An alternative would be to add version to the image tag of Synapse-related services. See #418

🟢 Should add a mention that we need to pull a runner image to be able to run a workflow. For example:
docker pull ghcr.io/serverlessworkflow/synapse/runner:1.0.0-alpha5

That shouldn't occur. The Docker Runtime should ensure that the configured image exists locally, or should attempt to download it.
I created #500 to address it.

🔴 I had to trick Synapse into running this alpha5 image by running this command:
docker tag ghcr.io/serverlessworkflow/synapse/runner:1.0.0-alpha5 ghcr.io/serverlessworkflow/synapse/runner:1.0.0

That is wierd. Given you have updated the operator's runner configuration using the UI, any image should work as expected. I guess the problem you faced is configuration-related. See #383, which has been long fixed.

🟡 The example workflow definition needs to be updated from:
...
🟡 We also need to mention that the version of the dsl property should match the version of the runner image that was pulled. Or at least that's what I thought. Am I wrong?

Yes, you are wrong, but understandably so. As a matter of fact, Synapse's version is different from that of the SDK it uses, which is up to 1.0.0. That's because, even though the spec is mature enough to have been released, there are still some fixes and features (ex: paging) that need to be implemented for Synapse to make it to (non pre)release.
In other words, if you are facing problems when using the dsl: '1.0.0', that's probably a bug, to address in a dedicated issue.

[LeifLazar]

Actually, suggested fixes would be but temporary, and would "force" user to build locally. An alternative would be to add version to the image tag of Synapse-related services. See #418

I have a few thoughts here:

• Sounds like there should be separate sets of instructions for different scenarios:
  • Using/Testing: run everything from existing images
  • Working on a service: run & debug that project from your IDE and everything else from existing images
  • Additionally, build and run an image from local code changes
• The first time setup for any of those scenarios should work all the time if the instructions are followed correctly. Being frustrated by just getting things up and running will deter users and/or contributors. I bet that a good chunk of the setup process can be automated by a few well placed scripts.
• The previous point leads into this image version issue. I think that there needs to be a good default state when pulling the main branch and running the images. Ideally, the main branch always triggers the publishing of updated images and it works with those by default so that what we're running represents the code that we just pulled.

I'm obviously not familiar enough with the project so I'll ask you to forgive me if I'm horribly wrong or if these ideas are already implemented.

[Kenzia1]

ghcr.io/microsoft/garnet