Applications and Websites

The WebFaction web hosting system works by keeping track of three important components of your account:

  • domains – domain names, like example.com (see Domains)
  • applications – a collection of directories, files, and processes used to serve data
  • websites – a record used in our system to determine which URLs should be served by which applications (see A Sophisticated Website Configuration)

In this section of the user guide, you will learn how to assemble domain names, applications, and your files into a complete website that your visitors can reach and use.

See also

The next chapter of the user guide, Example Websites, demonstrates common use cases.

Applications

To serve content, run code, and interact with databases, you need applications. Applications are collections of directories, files, and system settings which allow media to be served and code to be executed by the web server.

For example, an application could be as simple as a Static-only application storing a handful of HTML files and some JPEG images. In contrast, however, applications can be sophisticated software tools, like a Django application or the WordPress blogging engine. You can even run a Custom app (listening on port) to use software not covered by one of WebFaction’s one-click installers.

The control panel allows you to manage applications installed on your account. You can install a wide variety of applications, including:

  • AWStats
  • CherryPy
  • Django
  • Drupal
  • Passenger
  • Pylons
  • Python (Apache with mod_python or WSGI)
  • Ruby on Rails
  • Static-only
  • Static/CGI/PHP
  • Subversion
  • Trac
  • TurboGears
  • Webalizer
  • WebDAV
  • WordPress
  • Zope

You can also create a custom application, which lets you listen on a specified port.

When you create an application with the control panel, a directory is created in your home directory—$HOME/webapps/app, where app is the application name you entered on the control panel—along with any required files, like .htaccess or included scripts. If the application is a long-running process, the control panel installer also adds a cron job which periodically restarts the process if it stops running.

Note

An application cannot be reached from outside a WebFaction server without being configured in a website entry with the control panel. You’ll learn more about configuring website entries in the Websites section.

Create an Application with the Control Panel

See also

These directions show you how to create a new application unconnected to a website record. If you’re creating a website too, see Create a Website with the Control Panel for instructions to create websites and applications at the same time. If you’re creating an application that won’t be attached to a particular website record (such as a MongoDB installation), follow these directions.

To create an application with 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 an application category.

  6. In the App Type menu, click to select a specific application version.

  7. If applicable, in the Machine menu, click to select a web server.

  8. Review the application description. The description contains important details, cautions, and links to documentation.

  9. If applicable, in the Extra info field, enter any required information. See the application description for details.

  10. If applicable, choose whether to open this application’s port. In most cases, opening a port is not necessary; only open a port if you know you require it. If selected, the port is opened on a shared IP address and, if applicable, your dedicated IP address.

    To open the port, click to select Open a port in the server firewall for the application.

  11. Click the Save button.

The application is installed and added to the list of applications. If a port was opened, the applicable IP addresses appear beneath the list of installed applications.

Installing Applications Not Listed in the Control Panel

If an application or a version of an application you want to use is not listed in the control panel, don’t despair. First, check out WebFaction Software Documentation, in which we provide instructions for additional software packages not covered by a control panel installer. You can also install custom applications using one of the three “generic” application types:

  • Static/CGI/PHP: If the software you want to use can run directly from the document root directory, like many PHP software packages, use a Static/CGI/PHP application. Once you’ve installed the application, upload files to ~/webapps/static_app, where static_app is the name of the application.

  • Symbolic link to static/cgi/php: If the software you want to use needs only a subset of its files exposed to the web, use a Symbolic link to static/cgi/php application. When creating the application, enter the absolute path to the directory you want to expose to the web in the extra_info field. In all other respects, it works just like a Static/CGI/PHP application.

  • Custom app (listening on port): If the software you want to use listens on a network port, use a Custom app (listening on port). A Custom app assigns a specific port number where incoming traffic will be directed. Install the software and configure it to listen to the specified port.

If you need to repeatedly install an application not provided by the WebFaction control panel, see the api:index.

Websites

Usually, an application by itself isn’t particularly useful: it needs a web address—a domain name and a path—so it can be reached by a web browser. A website entry in the control panel connects an application to a domain and path. A website entry instructs your WebFaction web server to forward requests for a specific URL path to an application, and then return the application’s response.

The Life Cycle of a Request and Response

Requests to a URL path are received by a WebFaction server’s frontend process (an instance of the nginx web server). Such requests are proxied to a specific application’s process, such as a Django application’s instance of the Apache web server. The frontend process waits for a response from the application and forwards that response to the source of the original request.

Please see the diagram below for a closer look at how requests are received and replied to in a WebFaction server.

An illustration of how requests are handled by a WebFaction server

For example, suppose you have a Drupal application, my_drupal, and a domain, mysite.example. A website lets you configure mysite.example to point to your application, my_drupal. When a visitor opens http://mysite.example/ in their browser, your Drupal application will load at that URL. Behind the scenes, the web server proxies requests for mysite.example to the application stored at ~/webapps/my_drupal.

Hint

Creating a new site, but haven’t decided on a domain name yet? Or maybe you want to test the latest version of your site before taking it live on your existing domain name? Create subdomains of your username.webfactional.com domain to connect to your applications instead (like testsite.username.webfactional.com). See Adding a Domain to the Control Panel for more information.

Websites permit much more sophisticated configurations, however. You can configure a specific path (or mount point) at a domain to point to an application, allowing you to run multiple applications under a single domain. For example, suppose you have a pair of applications, a Drupal application called my_drupal and a Static/PHP/CGI application containing phpBB called forum, and a domain, mysite.example. You can configure a website to serve my_drupal from the root path (/) of mysite.example and forum from /forum:

mysite.example
    /       ->  my_drupal
    /forum  ->  forum

Domain and path combinations and applications may have a many-to-one relationship. While a particular domain and path combination can only point to one application, numerous domain and path combinations can point to the same application.

Create a Website with the Control Panel

To create a Website record (and any needed applications) with the control panel:

  1. Log in to the control panel.

  2. Click Domains / websites ‣ Websites. The list of websites appears.

  3. Click the Add new website button. The Create a new website form appears.

  4. In the Name field, enter a website name.

  5. If applicable, in the Machine menu, click to select the server to host the website.

  6. If applicable, in the IP address menu, click to select the IP address to serve the site.

  7. If you want your site served over an HTTPS connection, click to select Encrypted website (https).

  8. For each domain name you want to use with the website, add it to the list of domains. In the Domains field, enter the domain name. Enter one or more domain names. If the domain has not yet been added to the control panel, click the Create link that appears at the bottom of the list of domains to add it.

  9. Add one or more applications to the website.

    To add a new application:

    1. Click Add an application ‣ Create a new application. The Create a new web app form appears.

    2. In the Name field, enter a name for the application.

    3. In the App category menu, click to select an application category.

    4. In the App type menu, click to select a specific application version.

    5. If applicable, in the Extra info field, enter any required information. See the application description for details.

    6. If applicable, choose whether to open this application’s port. In most cases, opening a port is not necessary; only open a port if you know you require it. If selected, the port is opened on a shared IP address and, if applicable, your dedicated IP address.

      To open the port, click to select Open a port in the server firewall for the application.

    7. In the URL field, enter the URL path (for example, /blog).

      Note

      The first application added to a website is assigned to the root URL path (/).

    8. Click the Save button. The application is installed and added to website’s list of applications.

    To add an existing application:

    1. Click Add an application ‣ Reuse an existing application. The Reuse an existing web app form appears.

    2. Select the existing application on the website’s server to add to the website.

    3. In the URL field, enter the URL path (for example, /blog).

      Note

      The first application added to a website is assigned to the root URL path (/).

    4. Click the Save button. The application is added to the website’s list of applications.

  10. Click the Save button. The website is created and added to the list of websites.

Changes to website entries can take up to two minutes to take effect. As soon as the changes take effect, you can access each application at the URLs you picked. If at first a new or modified website is not working as expected, please wait at least two minutes and try again.

Secure Sites (HTTPS)

You can configure a website record to use HTTPS (Hypertext Transfer Protocol Secure), an encrypted alternative to an ordinary HTTP connection.

Note

The HTTPS setting is either on or off. Connections to the website entry are over the specified protocol only. If you need your site to be available over HTTP and HTTPS, then create two website records, one HTTP and the other HTTPS.

If you need your site to be served over HTTPS exclusively, then create a redirect from HTTP to HTTPS.

By default, HTTPS websites use WebFaction’s security certificate. Some browsers warn users that the domain doesn’t match the security certificate (though the connection is still encrypted). If you would like to use your own certificate, you must purchase an Apache/OpenSSL certificate through a certificate authority (CA). Your domain registrar may provide this additional service.

To enable your security certificate:

  1. Create an applicable website. The website must use a domain covered by your security certificate and HTTPS must be enabled.
  2. Upload the certificate and key files to your home directory.
  3. If you protected your key with a passphrase, remove the passphrase. The certificate cannot be enabled until you have removed the passphrase.
    1. Open an SSH session to your account.
    2. Enter openssl rsa -in keyfile.key -out keyfile.key2, where keyfile.key is the path to the keyfile, and press Enter.
  4. Open a support ticket to request activation of your certificate.

Note

In the past, security certificates required a dedicated IP address. WebFaction servers and most modern web browsers now support Server Name Indication (SNI), which generally eliminates the need for a scarce IPv4 address. If you’re concerned about supporting SNI-incompatible browsers, please open a support ticket to discuss the availability of a dedicated IP address.

Generating a Certificate Signing Request

If you are purchasing your own security certificate, you will be asked to provide a Certificate Signing Request (CSR). To generate a CSR:

  1. Open an SSH session to your account.
  2. Enter openssl genrsa -out domain.key 2048, where domain is your domain, and press Enter. A new file, domain.key, is created.
  3. Enter openssl req -new -key domain.key -out domain.csr and press Enter. Several prompts for details about the certificate will appear. When prompted for a Common Name, be sure to correctly enter the domain (or subdomain) for use with the certificate. When openssl is finished, the CSR file, domain.csr, is created.
  4. Enter more domain.csr and press Enter. The contents of your CSR file will appear in the console.
  5. Copy and paste the contents of your CSR file to your certificate provider’s form.

Reviewing Logs

You have complete access to your websites’ and applications’ logs in your home directory. You will find logs in your $HOME/logs directory, named according to the websites’ names in the control panel.

See also

To learn more about logs, please see Accessing Logs.

To generate statistics based on log files, see Webstats.