Skip to main content
This walkthrough takes an existing repository from no Keel configuration to a completed deployment. It uses a sample deployment that only prints, so you can run it without any cloud credentials.

​
Prerequisites

  • The keel CLI — see Install.
  • Docker running on this machine.
  • A repository to deploy. Any directory works; the sample does not need git.

​
Set up a repository

1

Create the starter files

From the repository root:
keel init never overwrites files that already exist. You get two:
  • keel.yaml — one sample deployment named production with one variable, GREETING, and two steps that echo it.
  • deploy/Dockerfile — the environment the steps run in. The starter is plain Alpine with bash, curl, and git.
2

Look at the configuration

Open keel.yaml. The parts that matter:
keel.yaml
Every variable becomes an environment variable inside the run and a form field in the UI. Every step is a shell script run inside a container built from the Dockerfile, with the repository mounted at /workspace.
3

Validate it

Validation reports every problem at once with the exact path of the offending key, so a broken file is quick to fix.

​
Deploy from the UI

1

Start Keel Dev

Open http://127.0.0.1:3400. The dashboard lists every deployment in keel.yaml. The file is re-read on every page load, so edits show up on refresh.
2

Create a target

Open the production deployment and create a target — call it local. A target is one concrete place the deployment goes, and it keeps its own values and run history. Real projects have one per client or per environment.
3

Fill in the variables

The target page renders a form from the variable declarations. Required fields that have no default are marked with a red asterisk; GREETING has a default, so you can leave it or change it. Press Save variables.Values are stored encrypted in .keel/dev.db. Because GREETING has a default, the target’s row on the deployment page already reads Ready to deploy; a variable without a default would show Needs 1 value until you filled it in, and the Deploy button would stay disabled.
4

Deploy

Press Deploy now. Keel builds the environment image from deploy/Dockerfile, starts a container with the repository mounted and GREETING exported, and runs the two steps. The run page shows a live log and a status per step:
The run finishes with the status succeeded. You just deployed.

​
Deploy from the terminal

Everything the UI does, the CLI does headlessly, which is how you wire Keel into scripts and CI:
keel deploy streams the same log to the terminal and exits non-zero when a step fails.

​
Make it real

Replace the sample with your project’s actual deployment:

Author a deployment

Turn a deploy script and a README section into steps and variables.

Environment images

Put the AWS, GCP, Terraform, or kubectl tooling your steps need into the Dockerfile.

Variables

Types, validation, secrets, defaults, and the form Keel renders from them.

Keel Cloud

Give the whole team a browser-based way to deploy, with roles and push-triggered runs.