Runp

name: Example
description: |
  Sample Runpfile to show runp functionalities
units:
  web:
    description: Web app
    # this process is running on host machine
    host:
      command: node app.js
      workdir: backend
      env:
        # inherit PATH from host system to find needed tools (e.g. node)
        PATH: $PATH
      await:
        # wait for the DB being available
        resource: tcp4://localhost:5432/
        timeout: 0h0m10s
  mail:
    description: Test mail server
    # this process is running in a container
    container:
      image: docker.io/mailhog/mailhog
      ports:
        - "8025:8025"
        - "1025:1025"
  db:
    description: Corporate DB
    # This process is reachable through SSH port forwarding
    ssh_tunnel:
      user: user
      auth:
        identity_file: ~/.ssh/id_rsa
      local:
        port: 5432
      jump:
        host: dev.host
        port: 22
      target:
        host: corporate.db
        port: 5432

runp --help                               # generic help
runp help up                              # describes the command "up"
runp up                                   # run the Runpfile in the current directory (default command)
runp --log-level debug up -f /path/to/runpfile.yaml
runp encrypt --key-env RUNP_KEY secret    # encrypt "secret" using the key from $RUNP_KEY
runp ls -f /path/to/runpfile.yaml         # list units in Runpfile
runp validate -f /path/to/runpfile.yaml   # validate Runpfile without starting
runp status                               # show runtime status of all units

export RUNP_FILE=/path/to/my/Runpfile
runp up
runp validate

runp up --file https://example.com/project/Runpfile
runp up --file http://intranet/Runpfile --checksum sha256:<64 hex characters>

container_runner: docker

runp config set container_runner podman
runp config get container_runner
runp config show

preconditions:
  os:
    inclusions:
      - linux
      - darwin

preconditions:
  runp:
    operator: GreaterThanOrEqual
    version: 0.10.0

preconditions:
  hosts:
    contains:
      127.0.0.1:
        - my.special.host
        - other.local

preconditions:
  env_vars:
    - name: DATABASE_URL
      condition: is_set

units:
  my-service:
    preconditions:
      env_vars:
        - name: MY_SERVICE_ENABLED
          condition: is_equal
          value: "true"
    host:
      command: "echo 'My service is enabled'"

name: My Project
include:
  - infra/Runpfile      # defines units: db, redis
  - services/Runpfile   # defines units: api, worker
units:
  proxy:
    host:
      command: nginx -g "daemon off;"

units:
  db:
    ready:
      cmd: "pg_isready -h localhost"
    container:
      image: postgres:15
      ports: ["5432:5432"]
  redis:
    ready:
      delay: 2s
    container:
      image: redis:7
  migrate:
    depends_on: [db]
    host:
      command: ./migrate up
  api:
    depends_on: [migrate, redis]
    ready:
      output: "listening"
    host:
      command: ./api-server
  worker:
    depends_on: [api]
    host:
      command: ./worker

units:
  zookeeper:
    description: Zookeeper
    stop_timeout: 0h0m15s
    container:
      name: zookeeper
      image: strimzi/kafka:0.19.0-kafka-2.5.0
      command: "bin/zookeeper-server-start.sh config/zookeeper.properties"
      ports:
        - "2181:2181"
      env:
        LOG_DIR: /tmp/logs

units:
  app:
    description: app
    host:
      command: echo hi
      env:
        PATH: $PATH
      await:
        timeout: 0h0m03s

units:
  be:
    description: Backend app
    host:
      command: mvn clean compile quarkus:dev
      workdir: backend
      env:
        # inherit PATH from host system to find mvn and java
        PATH: $PATH
      await:
        resource: tcp4://localhost:5432/
        timeout: 0h0m10s
  db:
    description: Database
    container:
      image: docker.io/postgres:alpine
      ports:
        - "5432:5432"
      env:
        POSTGRES_PASSWORD: pass
        POSTGRES_USER: user
        POSTGRES_DB: dbname

units:
  await:
    description: command
    host:
      command: env
      await:
        resource: file:///tmp/some_file.txt
        timeout: 0h0m9s
      env:
        MYHOME: ${HOME}

units:
  run:
    description: docker from shell
    host:
      command: docker run -t --rm hello-world
      workdir: /tmp
      await:
        resource: http://localhost:8000
        timeout: 0h0m25s
  hello-web:
    description: crccheck/hello-world
    container:
      image: crccheck/hello-world
      ports:
        - "8000:8000"

units:
  db:
    description: Database (ready after 3s warm-up)
    ready:
      delay: 3s
      timeout: 30s   # how long to wait before giving up (default: 30s)
    host:
      command: postgres -D /var/lib/pgsql/data
  api:
    description: App server (starts after db is ready)
    depends_on: [db]
    host:
      command: node server.js

units:
  api:
    description: App server (ready when "listening" appears in output)
    ready:
      output: "listening"
      timeout: 30s
    host:
      command: node server.js
  worker:
    description: Background worker (starts after api is ready)
    depends_on: [api]
    host:
      command: node worker.js

units:
  api:
    description: App server (ready when health endpoint responds)
    ready:
      cmd: "curl -sf http://localhost:8080/health"
      timeout: 60s
    host:
      command: ./api-server
  consumer:
    description: Consumer (starts after api health check passes)
    depends_on: [api]
    host:
      command: ./consumer

container_runner: /path/to/podman

name: Wordpress Runpfile
description: Runpfile to run Wordpress and MySql
units:
  db:
    container:
      name: db
      image: docker.io/mysql:5.7
      ports:
        - "3306:3306"
      env:
        MYSQL_ROOT_PASSWORD: somewordpress
        MYSQL_DATABASE: wordpress
        MYSQL_USER: wordpress
        MYSQL_PASSWORD: wordpress
  wordpress:
    container:
      image: docker.io/wordpress:latest
      ports:
        - "8000:80"
      env:
        WORDPRESS_DB_HOST: db:3306
        WORDPRESS_DB_USER: wordpress
        WORDPRESS_DB_PASSWORD: wordpress
        WORDPRESS_DB_NAME: wordpress
      await:
        resource: tcp4://localhost:3306/
        timeout: 0h0m20s

name: Containers Runpfile
description: This is Runpfile showing Docker volumes
units:
  fowler:
    description: The Fowler collection
    container:
      image: docker.io/alpine:3.12
      skip_rm: true
      mounts:
        - "type=volume,dst=/library/PoEAA"
        - "type=bind,src=/tmp,dst=/library/DSL"
      command: |
        echo "Fowler collection created"
  knuth:
    description: The Knuth collection
    container:
      image: docker.io/alpine:3.12
      skip_rm: true
      mounts:
        - "type=volume,dst=/library/TAoCP.vol1"
        - "type=volume,dst=/library/TAoCP.vol2"
        - "type=volume,dst=/library/TAoCP.vol3"
      command: |
        echo "Knuth collection created"
  reader:
    description: The avid reader
    container:
      image: alpine:3.12
      volumes_from:
        - fowler
        - knuth
      command: |
        ls -l /library/
      await:
        timeout: 0h0m3s

name: Test Runpfile
description: This is Runpfile
units:
  await:
    description: read environment variables
    host:
      command: set
      env:
        # in env block variables have always the unix notation
        MYHOME: ${HOME}
  echo:
    description: echo the value of %OS% env var
    host:
      # when used in command, env vars have the specific OS notation
      command: echo %OS%
  infiniteloop:
    description: infinite loop
    host:
      # this script is in examples/ directory
      executable: infinite.cmd
      workdir: examples

# Windows env vars
SystemRoot: ${SystemRoot}
ALLUSERSPROFILE: ${ALLUSERSPROFILE}
APPDATA: ${APPDATA}
CommonProgramFiles: ${CommonProgramFiles}
CommonProgramW6432: ${CommonProgramW6432}
ComSpec: ${ComSpec}
DriverData: ${DriverData}
HOMEDRIVE: ${HOMEDRIVE}
HOMEPATH: ${HOMEPATH}
LOCALAPPDATA: ${LOCALAPPDATA}
OS: ${OS}
PATHEXT: ${PATHEXT}
ProgramData: ${ProgramData}
ProgramFiles: ${ProgramFiles}
ProgramW6432: ${ProgramW6432}
PSModulePath: ${PSModulePath}
PUBLIC: ${PUBLIC}
SESSIONNAME: ${SESSIONNAME}
SystemDrive: ${SystemDrive}
TEMP: ${TEMP}
TMP: ${TMP}
USERNAME: ${USERNAME}
USERPROFILE: ${USERPROFILE}
windir: ${windir}

units:
  bash-process:
    description: a process that runs with bash
    host:
      command: "echo $BASH_VERSION"
      shell:
        path: /bin/bash
        args:
          - -c

units:
  win:
    description: Windows unit
    preconditions:
      os:
        # this unit is ran when os is windows
        inclusions:
          - windows
    host:
      command: dir {{vars runp_root}}
  unix:
    description: Nix unit
    preconditions:
      os:
        # this unit will be ran when os is linux or darwin
        inclusions:
          - linux
          - darwin
    host:
      command: ls -al {{vars runp_root}}

units:
  be:
    description: Backend app
    host:
      command: mybackendapp
      workdir: backend
  ldap:
    description: LDAP
    ssh_tunnel:
      user: runp
      auth:
        #identity_file: ~/tmp/runpssh/ssh/runp
        #secret: "plain text secret"
        encrypted_secret: "NsM1hcAy/L2TfACgfzbhYyb9j5a2ySYcARFDKkv7HTk="
      local:
        # localhost is the default
        port: 389
      jump:
        host: sshserver
        port: 22
      target:
        host: ldapserver
        port: 389
      # optional
      known_hosts_file: ~/.ssh/known_hosts
      test_command: "hostname"

export RUNP_SECRET_KEY=thekey
runp encrypt --key-env RUNP_SECRET_KEY SECRET

export RUNP_SECRET_KEY=thekey
runp up --key-env RUNP_SECRET_KEY

  env3:
    description: echo command
    host:
      command: echo ${MYHOME}
      workdir: ..
      env:
        MYHOME: ${HOME}

vars:
  foo: FOO_DEFAULT_VALUE
units:
  vars-test-unit:
    description: echo a user defined var
    host:
      command: echo __{{vars foo}}__

$ bin/runp --log-level debug up -f examples/Runpfile-vars.yml --var foo=bar

units:
  vars:
    description: echo implicit vars from Runp
    host:
      command: "echo runp_workdir={{vars runp_workdir}} runp_root={{vars runp_root}}"

NO_COLOR=1 ./bin/runp --log-level debug up -f examples/Runpfile-many-units.yml

./bin/runp --log-level debug --no-color up -f examples/Runpfile-many-units.yml

units:
  test1:
    description: test unit
    preconditions:
      runp:
        operator: GreaterThan
        version: 0.5.0
    host:
      command: env
      workdir: ${HOME}