WEB HOSTING SUPPORT NETWORK
     
 

Sureapp - app management CLI tool

The sureapp command is a powerful CLI (command-line interface) tool that allows you to create and manage web applications on your account. In order to use the sureapp tool, you need to connect to your account over SSH. You can connect to your account over SSH as described in the SSH section of our online documentation.

Here are some of the functionalities the sureapp tool offers:

Note: If you do not have a WebApps section in your Control Panel, then this tutorial is not suitable for your particular hosting environment. You can submit a support ticket through our ticketing system if you need assistance.

Getting help

If you call the sureapp command without any arguments, you will see a list of its commands.

To get help with a specific command and see its subcommands, you need to call:

sureapp help command

where you need to replace command with the actual command you wish to see help information for.

Here is a list of the available commands in the sureapp CLI tool:

  • project - This command allows you to create, modify, remove, and list projects.
  • service - This command gives you the ability to view and manage application services.
  • supervisor - This command allows you to control the service supervisor.
  • meta - This command displays meta information.
  • log - This command lists and allows you to view service logs.
  • env - This command allows you to control project environment.

For example, if you would like to see the subcommands and the help information of the sureapp project command, you need to call:

sureapp help project

Then, to see the help information of the sureapp project create command for example, you need to call:

sureapp help project create

Creating a web app

Generally, web apps can be created through the WebApps section of the Control Panel. This way, all necessary options can be configured via a visual interface. However, you can use the sureapp CLI tool to create web apps as well. This can be done with the sureapp project create command.

In order to create a web app through the command line, it is recommended that you first create the subdomain you wish to run the app on through the Subdomains section of the Control Panel, as well as the deployment directory for the web app. To see a list of the available options for the command, call the command without any arguments:

sureapp project create

In order to create a web app through the sureapp CLI tool, it is mandatory to specify the web app name and at least the following options:

  • --engine - This option allows you to specify the application engine. Its value can be either node or custom.
  • --engine-version - This option allows you to specify the application engine version. If the --engine option is set to custom, this option must be set to - (dash). Alternatively, if the --engine option is set to node, this option can be set to current, lts, or any of the versions available. To see a list of available engines and versions, call the sureapp meta engines command.
  • --release-dir - This option allows you to specify the application deployment directory. This directory must be a subdirectory of the /private directory on your account. This directory must contain the files of your application. You must specify the full path to your application's deployment directory.
  • --subdomain - This option allows you to specify the subdomain where the application will be accessible once it is running. The subdomain will not be created automatically if it does not exist. You must create the subdomain for your application through the Subdomains section of the Control Panel.
  • --domain - This option allows you to specify the domain where your application will be available once it is running. You can park domain names to your account through the Domain Parking section of the Control Panel.
  • --url-path - This option allows you to specify the URL path where your application will be available once it is running. You must specify the URL without the subdomain and the domain.

In addition, you can also specify the following options:

  • --notes STR - This option allows you to add free text notes.
  • --start-cmd STR - This option allows you to define a start command.
  • --rlimit-cpu INT - This option allows you to define the CPU timeout limit in seconds.
  • --rlimit-nproc INT - This option allows you to set the maximum number of processes (and threads) for the project.
  • --rlimit-core INT - This option allows you to set the upper limit on the size (in bytes) of core dump files.
  • --rlimit-data INT - This option allows you to define the maximum size (in bytes) of the process data segment.
  • --rlimit-as INT - This option allows you to set the maximum size of the process virtual memory bytes.
  • --rlimit-fsize INT - This option allows you to define the maximum size (in bytes) of files the process may create.
  • --rlimit-fileno INT - This option allows you to set the maximum number of opened files by the process.
  • --rlimit-stack INT - This option allows you to define maximum size (in bytes) of the process stack.

For example, if you would like to create a web app that will run on the current version of Node.js, available at http://www.yourdomain.com/path/to/your/webapp/, running from the /home/your_username/private/your_webapp_dir/ directory, and with the name MyWebApp, you need to call the sureapp project create command as follows:

sureapp project create --engine node --engine-version current --subdomain www --domain yourdomain.com --release-dir /home/your_username/private/your_webapp_dir/ --url-path /path/to/your/webapp/ MyWebApp

Please note that all options are case-sensitive.

Logging in to a web app shell

You can log in to a web app shell with the following command:

sureapp project shell MyWebApp

This command will log you in to the shell for the MyWebApp web app. You need to replace MyWebApp with the actual name of the web app you wish to manage. Most of the management commands of the sureapp tool work only after logging in to the web app shell.

Managing a web app

Modifying the settings of a web app

Once you log in to a web app shell, you can modify its settings with the sureapp project modify command. The command takes the same arguments as the sureapp project create command which is described in the Creating a web app section of this article.

For example, if you would like to change the engine of a web app to custom, you need to log in to the web app shell and call:

sureapp project modify --engine custom --engine-version -

Managing the state of a web app

You can enable, disable, start, stop, signal, and check the status of a web app with the sureapp service command. The command has several subcommands:

  • status - This subcommand allows you to view the current status of the application.
  • manage - This subcommand allows you to change the status of the application.
  • signal - This subcommand allows you to send signals to the application.

The sureapp service manage command takes the following options:

  • --enable - This option allows you to activate the service for the specified web app project.
  • --disable - This option allows you to stop any running instances and disable the web app project.
  • --start - This option allows you to start the web app as it is started via the WebApps section of the Control Panel.
  • --stop - This option allows you to stop the application as it is stopped via the WebApps section of the Control Panel.
  • --once - This option gives you the ability to run the web app once without restarting it if it exits.
  • --pause - This option allows you to pause the application temporarily (until resumed).
  • --resume - This option allows you to resume a paused application.

The sureapp service signal command takes the following options to send the corresponding signal to the application process tree:

  • --sigalrm, --SIGALRM - This option sends the SIGALRM signal.
  • --sighup, --SIGHUP - This option sends the SIGHUP signal.
  • --sigint, --SIGINT - This option sends the SIGINT signal.
  • --sigkill, --SIGKILL - This option sends the SIGKILL signal.
  • --sigquit, --SIGQUIT - This option sends the SIGQUIT signal.
  • --sigterm, --SIGTERM - This option sends the SIGTERM signal.
  • --sigwinch, --SIGWINCH - This option sends the SIGWINCH signal.
  • --sigusr1, --SIGUSR1 - This option sends the SIGUSR1 signal.
  • --sigusr2, --SIGUSR2 - This option sends the SIGUSR2 signal.

For example, if you would like to enable a web app, you need to log in to the web app shell and call:

sureapp service manage --enable

Managing the environment variables of a web app

Once you log in to the web app shell, you can manage the environment variables of the web app with the sureapp env command. The command has several subcommands:

  • set - This subcommand allows you to set environment variables.
  • unset - This subcommand allows you to unset environment variables.
  • list - This subcommand lists the project environment variables.

For example, if you would like to set the value of NEWVALUE to the variable VAR1 for a web app, you need to log in to the web app shell and call:

sureapp env set VAR1 NEWVALUE

Viewing the configuration of a web app

Once you log in to the web app shell, you can get the configuration values of the web app in a machine-readable format with the sureapp meta config command. The command has several options, depending on the format you would like to get the output in:

  • --json - This option will provide the web app configuration values in pretty printed JSON format.
  • --perl - This option will provide the web app configuration values in Perl Data::Dumper format.
  • --yaml - This option will provide the web app configuration values in YAML format.

For example, if you would like to get the configuration for a web app in pretty printed JSON format, you need to log in to the web app shelland call:

sureapp meta config --json

Viewing the logs of a web app

The sureapp CLI tool allows you to view and monitor the logs of a web app in real time. Once you log in to the web app shell, you can view and monitor logs with the sureapp log command. The command has several subcommands:

  • list - This subcommand lists the log files for project.
  • view - This subcommand allows you to view the contents of a specified log file.
  • follow - This subcommand allows you to follow (tail) a log file in real time.

For example, if you would like to monitor the logs for a web app, you need to log in to the web app shelland call:

sureapp log follow

Deleting a web app

Generally, web apps can be deleted through the WebApps section of the Control Panel. However, you can also delete web apps through the command line by using the sureapp project remove command of the sureapp CLI tool.

For example, if you would like to delete a web app named MyWebApp, you need to call:

sureapp project remove MyWebApp

Managing the web apps supervisor

The web apps supervisor is a system application that makes sure your web apps are running. The web apps supervisor can start, stop, or restart a web app when needed. It also manages the processes started by web apps. The web apps supervisor application itself can be managed through the command line with the sureapp supervisor command. The command has several subcommands:

  • start - This command allows you to start the supervisor service.
  • stop - This command allows you to stop the supervisor service.
  • restart - This command allows you to restart the supervisor service.
  • status - This command allows you to check the status of the supervisor service.
  • tree - This command allows you to view the process tree of the supervisor service.

For example, if you would like to check whether the web apps supervisor is running, you need to call:

sureapp supervisor status