Web Services

Last Updated October 2014

Web services house and run your application's source code are the entry point for any application. A single app can have multiple web services, each with their own code bases, unique configurations, and DNS Aliases. Each are independently scalable had have access to application databases, caches, and storage. This doc will walk through using and configuring web services. After reading it, you should be familiar with:

  • Using multiple web services
  • Configuring web services in the Boxfile
  • Basking in the warm light of web awesomeness

Creating a Web Service

Web services are created by including them in your Boxfile. A single application can have multiple web services. Once in your Boxfile, your web service(s) will be created during your next deploy.

Example Web Services in the Boxfile YAML

    name: front-end
    type: php
    version: 5.5
    httpd_document_root: public
    name: admin
    type: php
    version: 5.5
    http_document_root: admin
    name: api
    type: php
    version: 5.5
    httpd_document_root: api

Still all in One Repo

When using multiple web services, all your code is still housed in a single repo. For PHP web services, what directory a web service should run out of is determined by the httpd_document_root set for the service.

Once created, web services have access to any services included in your app (databases, caches, and storage). Connections to the other services simply need to be included in your codebase.

Configuring a Web Service

All configuration for web services is handled in the Boxfile. For details about specific languages and availalble configuration options, use the following docs:

Web Service Settings in the Boxfile

PHP Settings in the Boxfile
Apache Settings in the Boxfile

Routing to Web Services

Each web service can be accessed directly through a Pagoda Box development URL or through a custom domain.

Through Pagoda Box Dev URLs

Every app on Pagoda Box is given a development url: app-name.gopagoda.io. For apps with multiple web services, you can route to each service using the following URL structures:

  1. (service_id).(app-name).gopagoda.io
    Example: web1.myapp.gopagoda.io

  2. (service_name).(app-name).gopagoda.io
    Example: api.myapp.gopagoda.io

Know that web1 is assumed when routing to your base development URL. You don't need to include the service name or id when routing to web1.

Through Custom Domains

During and after the process of adding a DNS Alias, you can specify which service a custom domain should route to. Whenever multiple web services exist in an app, a dropdown will appear that allows you to choose to which web service the alias should route.

Use Cases

A Hybrid Scaling Model

An ecommerce store may have a heavy admin panel that may be better suited for a less concurrency (less instances) but higher RAM per instance for large routines. The front-end is much more optimized and would benefit from more concurrency (more instances) but with a smaller RAM footprint.

By splitting the admin panel and the front-end into two separate web services, they become independently scalable and can be scaled to suit their specific functions.

Service Sharing

You may have two completely unrelated applications, but would like to share a database or key/value store. Instead of creating two separate apps, you can launch an additional web service. This allows you to host two unique applications in complete isolation, yet share resources between the two.

This does introduce an interesting dynamic when it comes to workflow. Managing and collaborating on multiple applications in a single repo could become kind of cumbersome. One possible would be to have each application as it's own git submodule. Each submodule could be collaborated on and managed separately. When the main repo is pushed, git submodules will automatically be updated.

Simplicity & Organization

If you would like to keep your collaboration management and billing administration to a minimum, this allows multiple apps to be grouped within the same umbrella app namespace.

This use case would also benefit from managing the separate applications as git submodules as mentioned above.

If you have any questions, suggestions, or corrections, let us know.