Page tree
Skip to end of metadata
Go to start of metadata

 

Description

This function registers a Ruby application for an account.

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. 
  • We introduced this functionality in cPanel & WHM version 56.

 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.

Important:

An application name must contain 50 or fewer characters.

A valid string.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
  • production
production
envvar_namestring

A server environment variable.

Important:

  • You must pass this parameter for each envvar_value parameter that you pass.
  • 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.

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.shoes
envvar_valuestring

Each server environment variable's value.

Important:

  • You must pass this parameter for each envvar_value parameter that you pass.
  • An environment variable value must contain 1024 or fewer ASCII-printable characters.

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.ruby
enabledBoolean

Whether to enable the application and generate the Apache configuration.

This parameter defaults to 1.

  • 1 — Enabled.
  • 0 — Disabled.
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