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
  • Python (Apache with mod_wsgi)
  • Ruby on Rails
  • Static-only
  • Static/CGI/PHP
  • Subversion
  • Trac
  • Webalizer
  • WebDAV
  • WordPress

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 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 WebFaction API Documentation.

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 front end 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 front end 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:

    1. Click to select Encrypted website (https).

    2. In the Choose a certificate menu, click to select a certificate.

      The Shared certificate is WebFaction’s shared certificate. If you use the shared certificate, most browsers will warn that your domain doesn’t match the certificate (though the connection will still be encrypted).

      To add your own certificate, see Secure Sites (HTTPS).

    Note

    A website’s HTTPS setting is either on or off. Connections to the website are over the specified protocol only.

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

    If you need your site to be available over both HTTP and HTTPS, then create two website records, one HTTP and the other 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 any website record to use HTTPS (Hypertext Transfer Protocol Secure), an encrypted alternative to an ordinary HTTP connection.

Note

A website’s HTTPS setting is either on or off. Connections to the website are over the specified protocol only.

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

If you need your site to be available over both HTTP and HTTPS, then create two website records, one HTTP and the other HTTPS.

An HTTPS website requires an SSL/TLS certificate. By default, HTTPS websites will use WebFaction’s shared certificate, but you can also bring your own new or renewed certificate.

If you use WebFaction’s shared certificate, most browsers will warn that your domain doesn’t match the certificate (though the connection will still be encrypted). To set up your website to use HTTPS with WebFaction’s certificate, see Use a Certificate with a Website.

If you want to use your own certificate that matches your domain, then follow these steps:

  1. Get a certificate through a certificate authority. Your domain registrar may provide this additional service or you can get a free certificate from Let’s Encrypt. Depending on how your provider issues certificates, then you may need to generate a CSR first.
  2. Add the certificate with the WebFaction control panel.
  3. Use the certificate with a website.
  4. Whenever your certificate is soon to expire, renew your certificate.

Generating a Certificate Signing Request

If you are requesting a security certificate, you may be asked to provide a Certificate Signing Request (CSR). To generate a CSR:

  1. Log in to the WebFaction control panel.
  2. Click Domains / websites ‣ SSL certificates. The list of certificates appears.
  3. Click Generate a CSR. The CSR generator form appears.
  4. In the Country field, enter your country’s two-letter country code, such as US.
  5. In the State field, enter your state or province, such as California.
  6. In the Locality field, enter your city name, such as Los Angeles.
  7. In the Organisation field, enter your name, such as your company’s legal name or your personal name.
  8. In the Organisational unit field, enter your department, such as Marketing or IT.
  9. In the Common name field, enter the domain or subdomain name for use with the certificate, such as example.com or www.example.com.
  10. Optional In the Additional domains field, enter any additional domain names covered by the certificate, separated by spaces.
  11. Click Generate CSR. A Generated CSR dialog appears.
  12. Click Download CSR to download a zip file which contains both your CSR file and key file.

You now have a certificate signing request that you can give to your certificate provider.

Add a Certificate

A certificate authority (CA) typically issues a certificate and private key and Some CAs may also issue an intermediate certificate or bundle. You can recognize your certificate and keys by their distinctive PEM format, which looks like this:

-----BEGIN CERTIFICATE-----
MIIFIjCCBAqgAwIBAgISA+B6sUMfUeZK6oYwShXBLYjtMA0GCSqGSIb3DQEBCwUA
<more characters>
CIpIs5IBYwAw6wGgCdxtxOvTDjMvVw==
-----END CERTIFICATE-----
-----BEGIN PRIVATE KEY-----
MIIFIjCCBAqgAwIBAgISA+B6sUMfUeZK6oYwShXBLYjtMA0GCSqGSIb3DQEBCwUA
<more characters>
CIpIs5IBYwAw6wGgCdxtxOvTDjMvVw==
-----END PRIVATE KEY-----

To add your certificate, private key, and, if applicable, intermediate certificate or bundle, follow the directions for the method you’d like to use: uploading files or copying and pasting the certificate and key text.

Upload files:

  1. Log in to the WebFaction control panel.
  2. Click Domains / websites ‣ SSL certificates. The list of certificates appears.
  3. Click Add SSL certificate ‣ Upload certificate. The Upload certificate form appears.
  4. In the Name field, enter a name for the certificate, such as the name of the website or domain you plan to use the certificate with.
  5. In the Certificate section, click the Choose File button and select your certificate file.
  6. In the Private key section, click the Choose File button and select your certificate file.
  7. If your CA provided you with an intermediate certificate or bundle, then, in the Intermediates/bundle section, click the Choose File button and select your certificate file.
  8. Click the Save button.

Your certificate is added to the list of certificates. You can now use your certificate with a website.

Copy and paste:

  1. Log in to the WebFaction control panel.
  2. Click Domains / websites ‣ SSL certificates. The list of certificates appears.
  3. Click Add SSL certificate ‣ Copy & paste certificate. The Create a new SSL certificate form appears.
  4. In the Name field, enter a name for the certificate, such as the name of the website or domain you plan to use the certificate with.
  5. In the Certificate field, paste the text of your certificate, including the BEGIN and END lines.
  6. In the Private key field, paste the text of your certificate, including the BEGIN and END lines.
  7. If your CA provided you with an intermediate certificate or bundle, then, in the Intermediates/bundle field, paste the text of the intermediate certificate or bundle, including the BEGIN and END lines.
  8. Click the Save button.

Your certificate is added to the list of certificates. You can now use your certificate with a website

Use a Certificate with a Website

Once you’ve added a certificate to your account, you can configure a website to use the certificate.

To set up a new website record to use a certificate, see Create a Website with the Control Panel.

To modify an existing website record to use a certificate, follow these steps:

  1. Log in to the WebFaction control panel.

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

  3. Click the name of the website that you want to modify to use a certificate. The website’s details appear.

  4. In the Security section, click to select Encrypted website (https).

    Note

    A website’s HTTPS setting is either on or off. Connections to the website are over the specified protocol only.

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

    If you need your site to be available over both HTTP and HTTPS, then create two website records, one HTTP and the other HTTPS.

  5. In the Choose a certificate menu, click to select a certificate.

    The Shared certificate is WebFaction’s shared certificate. If you use the shared certificate, most browsers will warn that your domain doesn’t match the certificate (though the connection will still be encrypted).

  6. Click the Save button.

The website is now configured to use the certificate you selected.

Renew a Certificate

Periodically, your certificates will expire. To keep your sites secure and spare your visitors security error messages, you must renew your certificate with your certificate authority (CA) and then update your certificate with the control panel.

Once you’ve received the updated certificate from your CA, follow these steps:

  1. Log in to the WebFaction control panel.
  2. Click Domains / websites ‣ SSL certificates. The list of certificates appears.
  3. Click the name of the certificate that you want to update. The certificate’s details appear.
  4. In the Certificate field, paste the text of your certificate (replacing the existing text), including the BEGIN and END lines.
  5. In the Private key field, paste the text of your certificate (replacing the existing text), including the BEGIN and END lines.
  6. If your CA provided you with an intermediate certificate or bundle, then, in the Intermediates/bundle field, paste the text of the intermediate certificate or bundle (replacing the existing text), including the BEGIN and END lines.
  7. Click the Save button.

The certificate is now updated.

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.