Guide / Set up a project

Profiles

A profile is a named set of settings, such as test or prod, so one project can deploy to several places.

Free

Two words, two meanings

The word profile has two uses in Penstock. This page is about the second.

An engine profile is the kind of editor Penstock builds: Classic, Camunda 7, Camunda 8, Operaton or CIB seven. See Engines.
A deployment profile, or just profile, is a named block of overrides in penstock.yaml. Use one for each environment.

Define a profile

Open penstock.yaml.
Add a profiles block. Under it, give each profile a name and the keys that differ.

deployment:
  url: http://localhost:8080/engine-rest
  name: Order handling

profiles:
  test:
    deployment:
      url: https://bpm-test.example.com/engine-rest
      auth:
        type: basic
        username: ${BPM_USER:ci}
  prod:
    deployment:
      url: https://bpm.example.com/engine-rest
      auth:
        type: oauth
        clientId: penstock
        tokenUrl: https://auth.example.com/oauth/token

Anything a profile does not say keeps the value from above it. A profile may override any key, not only deployment.

Choose the profile in force

Set profile: test in the file, or
Set the environment variable PENSTOCK_PROFILE, or
Pass --profile test to a command. It sets the variable for that run.

The environment variable wins over the file. That is how a pipeline deploys to production without editing anything:

PENSTOCK_PROFILE=prod ./penstockw deploy . --wait

A profile is laid over the merged result of all penstock.yaml files, including penstock.local.yaml. So a profile beats a plain value in your local file. To override a profile on your own machine, put the key under profiles.<name> in penstock.local.yaml. This is exactly what the Connection dialog does when you enter an engine address for a profile. Environment variables come last. See penstock.yaml.

Deploy to another profile from the editor

Click the arrow next to Deploy.
Pick Deploy to <profile>. There is one entry for each profile, and Deploy to default for the plain settings.
The diagram goes there. The profile in force does not change.

The Deploy popover names every profile in the file, so a diagram can go to another environment without changing what is in force, and its Edit connection… edits the address and sign-in of the profile you picked. See Deployment.

See the profiles

$ penstock doctor
node        v22.12.0
root        /work/orders
config      penstock.yaml
engine      camunda-7
profiles    *prod, test
deployment  https://bpm.example.com/engine-rest - reachable (200)

The star marks the profile in force. penstock doctor --format json prints all the settings that apply after every layer, including the profile.

Secrets belong to the profile

In the editor, the password or client secret is stored in the secret store of your tool once for each profile. On the command line use PENSTOCK_PASSWORD, PENSTOCK_CLIENT_SECRET or PENSTOCK_TOKEN. Never write them into penstock.yaml. See Security and privacy.

What you see

penstock doctor lists the profiles and puts a star before the one in force.
The arrow next to Deploy shows one Deploy to <profile> entry for each profile.

Common problems

My profile is ignored.: Check the spelling and that profile or PENSTOCK_PROFILE names it exactly. penstock doctor lists the profiles it found and marks the one in force.
The profile in force is not the one I set in the file.: PENSTOCK_PROFILE wins over the file. Check your environment.
I set a value in penstock.local.yaml but the profile overrides it.: Right. A profile beats plain values in every file. Put the value under profiles.<name> in the local file.
The editor asks for the password again.: The password is stored per profile. A new profile has none yet.

Profiles

See also