webCOMAND

Package Routing Tutorial

In this tutorial, we will learn how webCOMAND automatically routes web requests to packages created in the repository.  Then, we will see how custom routes can also be defined to use your own domains and hostnames.

Automatic Routing

By default, webCOMAND will automatically route requests to packages defined in the repository.  URLs look like:

https://<account>.webcomand.com/<package>
  • <account> - Your webCOMAND account name.
  • <package> - The Package Namespace (see Packages Tutorial).

Path Routing

An optional path may follow the package and the full URL will be routed as follows.

  1. If a file within the package's public folder matches the path after the package exactly, process (if PHP) or serve the corresponding file.
  2. If the path ends with a folder and that folder contains index.php, process it.
  3. If the path ends with a folder and that folder contains index.html, serve it.
  4. If there is an index.php file in the package root folder, process it.
  5. Serve a "404 File not found" error.

Custom Routing

In addition to the automatic routing, custom package routes can be defined for arbitrary package aliases and/or hostnames.

Package Aliases

A package alias can be used to provide a shorter or friendlier name for a package, to be used in the URL instead of the typically longer package namespace.

For example, the Web Service Package has a Namespace of "io_comand_webservice", so it can be accessed at:

https://<account>.webcomand.com/io_comand_webservice

It also has a package alias of "ws", so it can also be accessed at:

https://<account>.webcomand.com/ws

To add a package alias:

  1. Launch Content Manager (CMS) App.
  2. In the folder tree on the left, expand and click: System / Route Settings
  3. Click the Add button (New Option) to add new Route Settings.
  4. Enter a Title like "Custom Routing".
  5. Click the Add button (New Option) in the Aliases field, within the Global tab.
  6. Select the desired Package, like "Presidents Demo".
  7. Enter the desired Alias, like "presidents".
  8. Click Approve

Now the Presidents Demo package can be accessed with a URL like:

https://<account>.webcomand.com/presidents

Hostnames

A custom hostname, such as "app.<yourdomain.com>", can be routed to a package as well.

You must register and own a domain in order to follow the steps below.  Replace <yourdomain.com> below with a domain name that you own and control.

There are two ways to configure DNS (choose one or the other):

CNAME Record

A CNAME record is easier to set up, maintain and supports automatic fail-over services included with paid webCOMAND accounts, so it is the generally recommended option.

To set up DNS with a CNAME record:

  1. Login to your domain registrar or DNS provider and navigate to DNS options for the domain.
  2. Add an CNAME record for "app" that points to your webCOMAND account hostname (ie. <account>.webcomand.com)

A Record

An A record is a little more trouble to set up and maintain, and requires DNS fail-over services with your own DNS provider, but it will be slightly faster to resolve, so it is recommended for more advanced users that want to squeeze out the best possible DNS performance.

To set up DNS with an A record:

First, get the IP address of your webCOMAND account (<account>.webcomand.com) with a DNS Lookup service like MX Toolbox.

Next, add a DNS record to point the custom hostname to your webCOMAND account.

  1. Login to your domain registrar or DNS provider and navigate to DNS options for the domain.
  2. Add an A record for "app" that points to your webCOMAND account IP address.

Next Steps

In either case, after the DNS A or CNAME record is set up, you can add a custom hostname within the custom Route Settings created above:

  1. Click the Web tab.
  2. Click the Add button (New Option) in the Web Routing field.
  3. Enter a Hostname, like: app.<yourdomain.com>
  4. Select a Default Package, like "Presidents Demo".
  5. Click Approve

At this point, you can now access the "Presidents Demo" Package at:

https://app.<yourdomain.com>
If you do not see the Presidents Demo package, DNS may not have been set up correctly.  Once DNS is configured, you will need to uncheck and recheck the Active checkbox and then click Approve to generate a new SSL certificate for the hostname.

All other webCOMAND packages can also be accessed under this URL.  For example, the Content Manager app can be accessed at:

https://app.<yourdomain.com>/cms

To disable all packages that aren't explicitly allowed as the Default Package or an Alias:

  1. Check the "Trusted Packages Only" checkbox.
  2. Click Approve

Conclusion

Now that you have seen how to configure package aliases and hostnames, you will be able to build any number of apps, each with their own unique alias and/or hostname.