Update Capstan Configuration Files Documentation

[KY64]

• Capstan version: v0.5.0
• OS: Fedora 33 x86_64
• Kernel version: 5.9.8-200

What Happened?

I was following step by step on how to create configuration file from the repo documentation. When I reach creating meta/run.yaml step, I couldn't get the exact output like the given example.

Problem

When I run this command

capstan runtime preview -r node

I got an output

Incorrect Usage: flag provided but not defined: -r

NAME:
   capstan runtime preview - prints runtime yaml template to the console

USAGE:
   capstan runtime preview [command options] [arguments...]

OPTIONS:
   --runtime value  Runtime name. Use 'capstan runtime list' to see available names.
   --plain          Remove comments (default: false)
   --help, -h       show help (default: false)

While according to the example, it should be

--------- meta/run.yaml ---------
runtime: node

config_set:

   ################################################################
   ### This is one configuration set (feel free to rename it).  ###
   ################################################################
   myconfig1:
      # REQUIRED
      # Filepath of the NodeJS entrypoint (where server is defined).
      # Note that package root will correspond to filesystem root (/) in OSv image.
      # Example value: /server.js
      main: <filepath>
      
      # OPTIONAL
      # A list of Node.js args.
      # Example value: node_args:
      #                   - --require module1
      node_args:
         - <list>
      
      # OPTIONAL
      # A list of command line args used by the application.
      # Example value: args:
      #                   - argument1
      #                   - argument2
      args:
         - <list>
      
      # OPTIONAL
      # Set to true to only run node shell. Note that "main" and "args" will then be ignored.
      shell: false
      
      # OPTIONAL
      # Environment variables.
      # A map of environment variables to be set when unikernel is run.
      # Example value:  env:
      #                    PORT: 8000
      #                    HOSTNAME: www.myserver.org
      env:
         <key>: <value>
      
      # OPTIONAL
      # Configuration to contextualize.
      base: "<package-name>:<config_set>" 

   # Add as many named configurations as you need

# OPTIONAL
# What config_set should be used as default.
# This value can be overwritten with --runconfig argument.
config_set_default: myconfig1
---------------------------------

It also happen when I try to run this command,

capstan runtime init -r node

How to reproduce

Installation

I follow the installation step on Fedora from this website http://osv.io/run-locally

sudo yum -y install https://repo.cloudrouter.org/1/x86_64/cloudrouter-repo-latest.noarch.rpm
sudo yum -y install capstan

After that I run the following command to check if it's installed successfully

capstan

Output,

NAME:
   capstan - pack, ship, and run applications in light-weight VMs

USAGE:
   capstan [global options] command [command options] [arguments...]

VERSION:
   v0.5.0

COMMANDS:
   config            Capstan configuration
   info              show disk image information
   import            import an image to the local repository
   pull              pull an image from a remote repository
   rmi               delete an image from a repository
   run               launch a VM. You may pass the image name as the first argument.
   build             build an image
   compose           compose the image from a folder or a file
   images, i         list images
   search            search a remote images
   instances, I      list instances
   stop              stop an instance
   delete            delete an instance
   package           package manipulation tools
   stack, openstack  OpenStack manipulation tools
   runtime           package runtime manipulation tools (meta/run.yaml)
   volume            volume manipulation tools
   help, h           Shows a list of commands or help for one command

GLOBAL OPTIONS:
   -u value             remote repository URL (default: "https://mikelangelo-capstan.s3.amazonaws.com/")
   --release-tag value  the release tag: any, latest, v0.51.0
   --s3                 searches and downloads from S3 repository at ("https://mikelangelo-capstan.s3.amazonaws.com/") (default: false)
   --help, -h           show help (default: false)
   --version, -v        print the version (default: false)

Step by step

Then I follow the step by step from the documentation

Solution

What needs to be done is pretty simple, instead of using -r I need to replace it with --runtime.

# capstan runtime preview -r node
capstan runtime preview --runtime node # This one is correct

and so,

# capstan runtime init -r node
capstan runtime init --runtime node # This one is correct

The documentation does not explain it, I think it should be updated with the current version so everyone won't get confused.

[KY64]

I just found out that when I try to run

capstan runtime preview

It tells me,

usage: capstan runtime preview -r [runtime-name]

It also happen when I run,

capstan runtime init

The output is,

usage: capstan runtime preview -r [runtime-name]

I might be wrong,
My question is will the upcoming version would add -r flag as a replacement/substitute for --runtime?

[wkozaczuk]

Hi,

Welcome to capstan and OSv community!

It looks like capstan documentation is incorrect in some places. This commit has upgraded the go module urfave/cli to version 2 which may have changed how long and short versions work and broke that part.

I need some time to figure out what exactly is wrong. It may not be soon as we are a very small community of volunteers.

If you are familiar with go and have some time, we would welcome a pull request fixing it :-)

[KY64]

Hi, thank you for the reply. I'm not really good at Golang for now.
I'll keep experimenting with the tool you created to get familiar of how it really works.