Installation

Let’s install up and deploy our very first service. By the end you will have up installed, a local control node, and two services live on whoami.localhost and weather.localhost.

1. Install the up CLI

Download the binary for your platform and put it on your PATH:

# Linux (amd64)
curl -fsSL https://github.com/karabohq/up/releases/latest/download/up-linux-amd64 -o /usr/local/bin/up
chmod +x /usr/local/bin/up

Confirm it runs:

up --version

It should print something like this:

up version 8915d7e-dirty

2. Start a control node

In up, we need one or more “nodes” that will run our applications and optionally build them. You can configure and use multiple nodes at once, see Concepts/Nodes.

However nodes you have, you will always need to have one “control node”. This is the node that will connect to all the other nodes and coordinate them.

We can setup the current machine as our first node, which will serve as our control node as well as run and build our applications.

up node init              # Initialises the current device as a node
up node enable            # Makes sure that this device is running as a node, and will restart our services when the node reboots

up node init writes ~/.config/up/config.toml with a generated auth token and registers this machine as a node with the control, build, and deploy roles. up node start then serves the control API on http://127.0.0.1:7070. The CLI reads the same config file, so there is nothing else to configure.

If you prefer to run the control node on another machine, point the CLI at it by setting node_url and node_token in ~/.config/up/config.toml to match that plane’s config.

See the Node commands for more information.

3. Create up.yaml

In up, you write an up.yaml file which contains a list of all your services (or applications), and their configuration. That file is the source of truth.

As an example, we can write a simple up.yaml that deploys the traefik/whoami image from Docker Hub.

In your project directory, write:

project: demo

services:
  - name: whoami
    source:
      type: image
      image: traefik/whoami:latest
    port: 80
    domains:
      - whoami.localhost

4. Deploy

Preview what will change, then apply:

up diff                   # This prints exactly what will be done so our service is deployed
up apply                  # This actuallys creates the service, pulls the image and then runs it

Check the documentation for the up diff and up apply commands.

5. See it live

Visit http://whoami.localhost.

You have deployed your first service with up!

Note: you could have done all this without writing an up.yaml file by running these commands, but I believe having an up.yaml is more convenient.

up project create demo
up service create --project demo whoami --image traefik/whoami:latest --port 80 --domain whoami.localhost
up service deploy --project demo whoami

See the Command reference for more information.

up diff actually runs the same logic underneath, but I believe having an up.yaml with a singular source of truth can be beneficial.

6. Build from source

Besides running pre-built containers, up also supports building projects from source from a git remote.

Here, we are going to deploy a demo weather application that will be built using Railpack, but we also support building projects using a Dockerfile.

We deploy “from-source” applications by first building a specific branch, tag, or commit, then pushing that image to a Registry, which will allow us to store the built application images and deploy them to different nodes.

Hence, we need to run a local registry, but you can also use other registries like ghcr.io, Docker Hub, etc…

podman run -d \
  --name registry \
  -p 5000:5000 \
  -v registry-data:/var/lib/registry \
  docker.io/library/registry:2

Then extend up.yaml:

# yaml-language-server: $schema=./schema/up.yaml.schema.json
project: demo

services:
  - name: whoami
    source:
      type: image
      image: traefik/whoami:latest
    port: 80
    domains:
      - whoami.localhost

  - name: weather
    source:
      type: git
      url: https://github.com/s-shemmee/React-Weather-App
      ref: main
    build:
      type: railpack
      output_registry: local
    port: 80
    domains:
      - weather.localhost

environment:
  name: production

registries:
  - name: local
    host: 127.0.0.1:5000

Apply and visit http://weather.localhost:

up apply