Tutorial

The WebFaction API allows you to write scripts to automate certain tasks that you would normally accomplish with the control panel or an SSH session.

For instance, you could use the API to write a script to configure lots of email addresses, instead of creating them one by one in the control panel.

You can also use the API to automate the installation of any application that you like, and you can share the resulting install script to allow other users to use it in one click.

Getting Started

The API is a set of methods available via XML-RPC calls at the URL https://api.webfaction.com/. In this documentation we will use the Python programming language to talk to the API, but you can use any language that you want, provided that it has an XML-RPC library.

First, connect to the server and login:

>>> import xmlrpclib
>>> server = xmlrpclib.ServerProxy('https://api.webfaction.com/')
>>> session_id, account = server.login('test5', 'password')
>>> account
{'username': 'test5', 'home': '/home2', 'id': 237}

The username and password passed to the login method are those used to login to the control panel.

As you can see, the login method returns a tuple. The first element is a string containing a session ID that you will need to pass to all subsequent methods. The second element is a dictionary containing various data about your account, including the base home directory (usually /home or /home2).

Creating an Email Address

Let’s create a new email address for our account:

>>> server.create_email(session_id, 'user@mydomain.example', 'test5')
{'email_address': 'user@mydomain.example', 'id': 2037, 'targets': 'test5'}

The create_email method takes the session ID, the email address and a string of comma separated target mailboxes. It returns a dictionary containing various data about the newly created email address.

This call is equivalent to creating the email address from the control panel, but the advantage is that you can script it.

Installing an Application

Now let’s see which methods we can use to install an application. For this tutorial, let’s install a Joomla application.

First, create a Static/CGI/PHP application:

>>> server.create_app(session_id, 'my_joomla_app', 'static', False, '', False)
{'app_type': 'static',
 'name': 'my_joomla_app',
 'id': 3901,
 'autostart': False,
 'port': 0,
 'open_port': False,
 'extra_info': ''}

create_app uses the following parameters:

  • session_id – session ID returned by login
  • name (string) – name of the application
  • type (string) – type of the application
  • autostart (boolean) – whether the app should get restarted with an autostart.cgi script
  • extra_info (string) – additional information required by the application (for example, a file path). If extra_info is not required by the application, it is ignored.
  • open_port (boolean) – for applications that listen on a port, whether the port should be open on shared and dedicated IP addresses

Calling create_app is equivalent to creating the application through the control panel: it creates the directory and configures everything that’s needed for this application.

Next, you need to download the Joomla tarball and untar it in the app directory. To do so we’ll use the system method of the API, which allows us to execute some command on our server as if we were logged in with SSH. Since the default Static/CIG/PHP app comes with an index.html file which would shadow the index.php file provided by Joomla, we will also delete that file:

>>> cmd = "rm -f index.html;"
>>> cmd += "wget https://wiki.webfaction.com/attachment/wiki/JoomlaFiles/Joomla_1.5.0-Beta-Full_Package.tar.gz?format=raw"
>>> cmd += "tar xzvf Joomla_1.5.0-Beta-Full_Package.tar.gz?format=raw"
>>> server.system(session_id,  cmd)
''

Because we previously installed an application, the system method automatically runs in the new application’s directory. The system method returns whatever the command printed to standard output. If the command prints something to standard error, system raises an error with that text.

Next, create a MySQL database, since Joomla requires one:

>>> server.create_db(session_id, 'test5_joomla_db', 'mysql', 'db_password')
{'type': 'mysql',
'id': '1161011151160530951061111111091080970951000980451',
'name':'test5_joomla_db'}

This creates a MySQL database called test5_joomla_db and a user of the same name, with the password db_password.

Next, copy the Joomla config file from configuration.php-dist to configuration.php and then edit it to specify the database connection settings:

>>> server.system(session_id, "cp configuration.php-dist configuration.php;")
''
>>> server.replace_in_file(session_id, 'configuration.php',
        ("var $user = '';", "var $user = 'test5_joomla_db';"),
        ("var $password = '';", "var $password = 'db_password';"),
        ("var $db = '';", "var $db = 'test5_joomla_db';"))
''

The handy replace_in_file method lets us find and replace in a file. It takes a session ID, the name of the file, and any number of tuples containing a string to replace and the replacement string.

There are a few other steps needed to install a Joomla application: we need to edit the Joomla SQL file and run it. We won’t detail them here—you can look at the actual script for details.

Packaging the Install Script for the Control Panel

Previously, we installed a Joomla application by manually running a bunch of commands. We can package these commands in an install script for the control panel to run for us. The advantage is that we can then run this install script over and over again directly from the control panel or share it with others.

How the Install Script is Run

To use an install script in the control panel:

  1. Log in to the control panel.
  2. Click Domains / websites ‣ Applications. The list of applications appears.
  3. Click the Add new application button. The Create a new application form appears.
  4. In the Name field, enter a name for the application.
  5. In the App Category menu, click to select Custom. The Script URL field appears.
  6. In the Script URL field, enter the install script’s URL.
  7. Click the Fetch URL button.
  8. If applicable, in the Machine menu, select a web server.
  9. Click the Save button.

When you click the Create button, the script is run with the following parameters:

install_script create|delete username password app_name autostart extra_info

  • username – control panel username
  • password – user’s hashed password
  • app_name – application name from Name field.
  • autostart (boolean) – whether the user selected the Autostart checkbox
  • extra_info – contents of the Extra info field.

When the user creates the app, the control panel will call the script with create as the first parameter. If the user deletes the app later on, the control panel will call the script with delete as the first parameter.

When it calls the script with create, the control panel expects the script to print the application ID to standard output and nothing else. If the script prints anything else to standard output, or prints anything to standard error, the control panel will display it as an error message on the add application page.

When it calls the script with delete, the control panel expects your script to not print anything to standard output or standard error. If anything gets printed the control panel will display it as an error message.

Additionally, if your script is written in Python and you include a docstring (PEP 257) at the beginning of the script, the control panel will use it as the application documentation.

To see two examples of install scripts, take a look a the Joomla install script or the MoinMoin install script.

Making a Script Available in One Click

Now that you have your install script, one way to share it would be to ask others copy and paste it in the control panel. That’s not convenient but fortunately, there is a better way.

On the add application page in the control panel, there is a field Install script url that appears when you select Custom install script. If you enter a URL and click Fetch URL, the control panel will look for an install script at that URL. For the control panel to find the script on the page, your script must be enclosed between these two magic tags:

-----BEGIN WEBFACTION INSTALL SCRIPT-----
-----END WEBFACTION INSTALL SCRIPT-----

If you make your script available on the web, all you have to do to let anyone use it is give them a special URL in the form https://my.webfaction.com/app/new-application?script_url=location where location is the escaped URL to your script.

You can see examples at InstallScripts, where Joomla, MoinMoin, and other applications can be installed using that approach.

Additional Resources

For more information about the WebFaction API, please consult the API Reference.