Child pages
  • UAPI Functions - PassengerApps::register_application
Skip to end of metadata
Go to start of metadata

Description

This function registers a Ruby application for an account.

Important:

This function only registers an application. It does not create the application. You must create an application before you register the application. For an example of how to do this, read our How to Create Ruby Web Applications documentation.


Examples


 cPanel or Webmail Session URL
https://hostname.example.com:2083/cpsess##########/execute/PassengerApps/register_application?name=slippers&path=%2Fslippers&domain=dorothy.com&deployment_mode=production&envvar_name-1=shoes&envvar_value-1=ruby&envvar_name-2=tinman&envvar_value-2=heart&enabled=1


Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
 // Register the slippers application.
$poll = $cpanel->uapi(
    'PassengerApps', 'register_application',
    array(
        'name' 			  => 'slippers',
        'path' 			  => '/slippers',
        'domain' 		  => 'dorothy.com'
		'deployment_mode' => 'production',
		'envvar_name-1'	  => 'shoes',
		'envvar_value-1'  => 'ruby',
		'envvar_name-2'	  => 'tinman',
		'envvar_value-2'  => 'heart',	
		'enabled'		  => '1',
  )
);


Note:

For more information, read our Guide to the LiveAPI System.

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
 
#  Register the slippers application.
my $poll = $cpliveapi->uapi(
    'PassengerApps', 'register_application',
    {
        'name'    		  => 'slippers',
        'path'    		  => '/slippers',
        'domain'  		  => 'dorothy.com',
		'deployment_mode'  => 'production',
		'envvar_name-1'	  => 'shoes',
		'envvar_value-1'  => 'ruby',
		'envvar_name-2'	  => 'tinman',
		'envvar_value-2'  => 'heart',	
		'enabled'		  => '1',
  }
);


Note:

For more information, read our Guide to the LiveAPI System.

 cPanel Template Toolkit
<!-- Register the slippers application. -->
[% execute('PassengerApps', 'register_application', { 'name' => [% execute('PassengerApps', 'register_application', { 'name' => 'slippers', 'path' => '/slippers', 'domain' => 'dorothy.com', 'deployment_mode' => 'production', 'envvar_name-1' => 'shoes', 'envvar_value-1' => 'ruby', 'envvar_name-2' => 'tinman', 'envvar_value-2' => 'heart', 'enabled='1' } ) %]


Note:

For more information, read our Guide to Template Toolkit documentation. 

 Command Line
uapi --user=username PassengerApps register_application name="slippers" path="/slippers" domain="dorothy.com" deployment_mode="production" envvar_name-1="shoes" envvar_value-1="ruby" envvar_name-2="tinman" envvar_value-2="heart" enabled="1"


Notes:

  • You must URI-encode values.
  • username represents your account-level username.
  • For more information and additional output options, read our Guide to UAPI documentation or run the uapi --help command. 

 Output (JSON)
{
    "messages": null,
    "errors": null,
    "status": 1,
    "metadata": {},
    "data": {
        "slippers": {
            "base_uri": "/ruby",
            "domain": "dorothy.com",
            "enabled": 1,
            "envvars": {
                "slippers": "ruby"
				"tinman": "heart"
            },
            "name": "slippers",
            "path": "/home/dorothy/slippers"
            "deployment_mode": "production"
        }
    }
}


Note:

Use cPanel's API Shell interface (cPanel >> Home >> Advanced >> API Shell) to directly test cPanel API calls.

Parameters

ParameterTypeDescriptionPossible valuesExample
namestring

Required

The application's name.

A valid string.

Important:

An application name must contain 50 or fewer characters.

slippers
pathstring

Required

The application's filepath.

A valid filepath, relative to the user's /home directory.

/slippers
domainstring

Required

The domain for which to register the application.

A valid domain on the cPanel account.dorothy.com
deployment_modestring

The type of server environment in which to run the application.

This parameter defaults to production.

  • development — Sets the application to run in a development environment.
  • production — Sets the application to run in a production environment.
production
envvar_namestring

A server environment variable.

Important:

You must pass this parameter for each envvar_value parameter that you pass.


Note:

To add multiple environment variables, you must increment this parameter. For example, envvar_name-1, envvar_name-2, envvar_name-3.

If you do not use this parameter, the function does not configure the application's environment variables in Apache®.

A valid string.

Important:

This parameter's value can only contain letters, numbers, underscores, and dashes, and cannot begin with a number. This parameter's value must also not exceed 256 characters.

shoes
envvar_valuestring

Each server environment variable's value.

Important:

You must pass this parameter for each envvar_name parameter that you pass.


Note:

To add multiple environment variable values, you must increment this parameter. For example, envvar_value-1, envvar_value-2, envvar_value-3.

If you do not use this parameter, the function does not assign a value to an environment variable.

A valid string.

Important:

An environment variable value must contain 1024 or fewer ASCII-printable characters.

ruby
enabledBoolean

Whether to enable the application and generate the Apache configuration.

This parameter defaults to 1.

  • 1 — Enable.
  • 0 — Disable.
1

Returns

ReturnTypeDescriptionPossible valuesExample
application namehash

A hash that contains an application's configuration information.

Note:

The hash's name is the application name.

This hash contains the base_uri, domain, enabled, name, path and deployment_mode returns and the envvars return.

 

base_uri

string

The application's base URI.

The function returns this value in the application name hash.

A valid URI./ruby

domain

string

The domain for which the function registered the application.

The function returns this value in the application name hash.

A valid domain on the cPanel account.dorothy.com

enabled

Boolean

Whether the application is enabled.

The function returns this value in the application name hash.

  • 1 — Enabled.
  • 0 — Disabled.
1

envvars

hash

A hash of application environment variables and their values.

The function returns this value in the application name hash.

A hash of valid environment variables and their values. 

name

string

The application's name.

The function returns this value in the application name hash.

A valid application name.slippers

deployment_mode

string

The type of environment in which the application will run.

The function returns this value in the application_name hash.

  • development
  • production
production

path

string

The application's filepath.

The function returns this value in the application name hash.

A valid filepath./home/dorothy/slippers