Skip to content

Standard Specification

Jump to bottom
cryi edited this page Feb 20, 2020 · 2 revisions

AMI is a standard for packing applications into consistent and easily-deployable packages.

General

AMI works in the current working directory, or in a directory specified by --path=<path>.

Folder structure

  • App root folder
    • app.json/app.hjson App config created/configured by user
    • ami.lua (optional) Contains any custom overrides for AMI.
    • model.lua Contains an on-setup-generated app model, which may be used for template rendering and internal function execution
    • specs.json These are the specs of the top-most layer, which are treated as the specs for the entire application. Any specs files for other (lower) layers are discarded after setup.
    • data/ A folder where application-related data can be found. While it is strongly recommended to name this folder data/, some applications may need some flexibility, so this is not enforced.
    • __*/ Directories prefixed with __ should contain all files related to this app's layers.
    • .ami-templates Contains file templates (files with names of form name.extension.template or name.template.extension) which are parsed and rendered into their output files during setup --configure

Only app.json/app.hjson should be manipulated - all other files are autogenerated or managed by AMI.

Commands

Unless tagged as (optional), the below commands must be implemented to ensure compliance with the AMI specification.

All commands (including optional commands) must end with exit code 0 on success, and with a non-zero exit code on failure.

start

Starts the application.

stop

Stops the application.

setup

Installs the application. Supports --app and --configure flags. If no flag is specified, both are used.

  • --app Fetches any required layers and builds the application
  • --configure Configures application based on app.json/app.hjson. Any setup-related action that depends on these config files should be performed through --configure. Note: this flag should only be used without --app if a prior setup has already been performed with --app.

info

Prints runtime information about the application. This message must contain:

  • status (string) - runtime status message
  • level "ok" | "warn" | "error" - current overall status

Other fields are optional.

Note: info must implement the --json flag, which prints information in json format (on a single line i.e. not pretty-printed).

validate

Checks the config files (app.json/app.hjson), environment, platform etc. for values that you expect.

If no validation is required, simply return 0.

about

Prints information about application, such as author, version, etc.

Note: about must implement the --json flag, which prints information in json format (on a single line i.e. not pretty-printed).

remove

If no flags are specified, removes application data (usually the data/ folder, or any custom data folders).

Note: remove must support the --all flag which (if specified) removes the entire application except app.json/app.hjson (config files).

optional commands

An application-specific AMI implementation (ami.lua) can specify additional commands.

You can check available commands at runtime with ami --path=<path> --help.

Clone this wiki locally