Your first app in 5 minutes

In this tutorial you run a small web app on the platform and give it a secret from a vault. You need no repository and no code of your own: the app is a ready-made container image. Everything goes into a new resource group, so at the end one deletion removes it all again.

What you will build

• A resource group that holds everything else.
• A vault with one secret, greeting.
• An app that runs the image registry.stackship.se/public/tutorial-app:1. Its managed identity — the identity the app acts as — gets the Secrets Reader role on the vault, and the app gets a reference to the secret.

When you open the app, it shows the value of greeting, which proves that the secret reached it.

Important

The sample app shows the value of its GREETING secret only because it is a harmless example made for this tutorial. A real app must never display a secret's value — not on a page, in a log or in an error message.

Before you start

• You need the Owner role on a boundary: it lets you create the resource group, the vault and the app, and assign roles. Contributor can do everything except assigning the role in step 6; ask an Owner of the boundary to do that for you.
• The boundary needs a cluster to put resources on — see Before you start in Create a resource group.
• The cluster must be able to pull images from registry.stackship.se. On an installation without access to the internet, ask your platform administrator.

Step 1: Sign in

Open the portal at https://portal.example.com and sign in. If the portal asks you to Select a Boundary, pick the boundary you want to work in and choose Continue. The portal opens the Dashboard; the boundary you work in is shown at the top of the sidebar.

Step 2: Create a resource group

1. Open Resource Groups in the sidebar and choose Create Resource Group.
2. Enter a Resource Group Name, for example my-first-app: 3 to 50 lowercase letters, digits and hyphens, starting and ending with a letter or digit, and not already used in the boundary.
3. Choose Create.

The group is listed as Provisioning. The Notifications panel opens by itself to follow the creation — it does so whenever you start something, and closes when you click elsewhere. After a few seconds a notification says Resource group ready., and the group is ready to use. More about resource groups: Create a resource group.

Step 3: Create a vault

1. Open Secret Vaults in the sidebar — it is under Security — and choose Create Secret Vaults.
2. On Basics, enter a Vault Name. The name is part of the vault's address, so it must be unique on the whole platform, not only in your boundary: make it your own, for example my-first-app-jane. Under Resource group, pick the group you just created; it is filled in already when it is the only one.
3. Choose Next twice — the defaults of Vault Configuration are fine — and then Submit on Review & Create.

The vault is listed with the status Ready within seconds. More about vaults: Create a vault.

Step 4: Add a secret

1. Open the vault from the list, go to its Secrets section, and choose Add Secret.
2. Enter the Name greeting, and as the Value a short message of your own, such as Hello from my first app.
3. Choose Create Secret.

The secret is listed as Enabled, version v1.

Step 5: Create the app

1. Open App Service in the sidebar — under Compute — and choose Create Apps. The wizard has eight steps; choose Next to go from one to the next.
2. Basic Configuration: enter the App Service Name hello, and pick your group under Resource group.
3. Instance Details: pick any Runtime stack and Version, for example Node and 22. An app that runs a container image does not use them, but the wizard asks for them. Leave Port at 3000: the sample app listens on it.
4. Networking: leave it as it is.
5. Compute Plan: pick Small — the sample app needs very little.
6. Scaling: leave it as it is, one replica.
7. Deployment Source: set Deployment Source Type to Container, and enter the Container Image registry.stackship.se/public/tutorial-app:1.
8. App Settings: leave it empty. Secrets are not added here but in step 7 of this tutorial.
9. Review & Create: check the summary and choose Submit.

You return to the app list. The app is Creating while the platform pulls the image and starts it, and Running once it answers on its port, usually within a minute — see Statuses.

Open the app from the list. On its Overview, the Managed Identity card shows the app's Principal ID. Copy it with the copy button next to it: you need it in the next step.

Step 6: Give the app access to the vault

The app reads its secrets as its managed identity, and that identity starts with no access at all. Give it the Secrets Reader role on the vault before you add the secret to the app: an app whose identity may not read the vault does not start.

1. Open Secret Vaults, open your vault, and go to its Access Control section.
2. Choose Add role assignment.
3. Paste the Principal ID into the Principal search field, and pick hello, listed as a Service.
4. As the Role, pick Secrets Reader, and choose Add assignment.

The list now shows hello with the role Secrets Reader and the scope This resource. More about this step: Give a workload access to a vault.

Step 7: Add the secret to the app

1. Open App Service, open hello, and go to its Configuration section.
2. Choose Secrets in the list beside the settings — on a narrower screen, in the drop-down above them.
3. Choose Add Secret. In Add Secret Reference, pick your Vault and the Secret greeting. The Environment Variable Name is filled in as GREETING; keep it, because that is the name the sample app looks for.
4. Choose Add, and then Save.

Saving deploys the app again with the secret: the app shows Updating, and Running again when its new instance is ready, usually within a minute.

Despite the field's name, GREETING does not become an environment variable. The app finds its secrets in the file /secrets/env.json, which maps each Environment Variable Name to the secret's value — see Read the values in an app.

Step 8: Open the app

Choose Browse at the top of the app's page. The app opens in a new tab at its own address, a hostname under apps.example.com. The page, Hello from Stackship, shows the message you stored in greeting, and lists the secrets the app was given: GREETING.

If the app does not get back to Running after step 7, check that step 6 was done, on the right vault — see The workload does not start.

Step 9: Clean up

Everything you created is in the resource group, so deleting the group removes it — the role assignment you made on the vault included.

Open Resource Groups, choose the delete button on your group's row, type the group's name to confirm, and choose Delete.

The group shows Deleting and then disappears from the list; the resources in it are removed in the background — see Follow the deletion.

Next steps

• Create an app from your own repository
• Environment variables and secrets
• Use a managed identity in code
• Use your own domain