Coding a Quickstart
Quickstarts make it easy for users to launch fully-functional web applications on Pagoda Box with a single click. Using tools and functionality built-in to Pagoda Box, you can create Quickstarts to sell and/or share with the development community and earn money as people use them. This doc will walk you through what you need to know and what tools you have available when coding a Quickstart. After reading it, you should be familiar with:
- Things to know when coding a Quickstart
- Tools to use when coding a Quickstart
- Rocking the Development World — because that's what you're going to do
Things to Know When Coding a Quickstart
Pagoda Box is not your typical hosting platform. We've built our service from the ground up to allow any web application to seamlessly scale in a distributed cloud environment. To do this, we've done things differently than your run-of-the-mill web host. Below are important things to know when creating Quickstarts. For a detailed rundown of how Pagoda Box is different, check out the Understanding the Environment doc.
Pagoda Box is a Read-Only Environment
For security reasons and because a single application on Pagoda Box can be spread across multiple servers, applications are read-only. This keeps web instances from writing themselves out of sync.
You are able to specify network directories in the Boxfile – centralized, writable directories connected to each of your services' instances – but these should be used sparingly, especially when creating a Quickstart. Any files stored within a directory specified as a network directory will not be available after deploy. We create a network mount over network directories, connecting them to a single file system shared across all web and worker instances, hiding any files already existing within those directories inside your repo. This allows instances to stay in sync as they write to files. We recommend using network directories for things like user-uploaded content and any other written content that need to stay in sync across instances. For an in-depth look at network directories and storage, check out the Network Storage doc.
Many popular frameworks and web-applications use auto-install scripts that directly modify config files based on environment settings and/or user-specified configurations. Because Pagoda Box is a read-only environment, auto-installers will not work. There are many different approaches you can take to accomplish the same end-goal of an auto-installer. Below are just a few ideas:
Include pre-built config files utilizing Environment Variables
Store user-specified configurations in a database
Utilize Build & Deploy Hooks to dynamically configure apps on deploy
Tools to Use When Coding a Quickstart
Pagoda Box provides some great tools to help you to build your own Quickstarts. These tools aren't necessary for all Quickstarts, but each offers very specific types of functionality that you may need.
The Boxfile is used to configure an app's environment on Pagoda Box — everything from network directories, to php versions. For the full Boxfile documentation, check out the Boxfile doc.
A feature of the Boxfile that is incredibly useful when creating Quickstarts is how it acts as an infrastructure "seed" file. Basically, any service that is included in the Boxfile will automatically be created on deploy. This means you're able to launch databases, caches, workers, etc., simply by including them in your Boxfile.
The Boxfile.install is a Boxfile that is honored on only the initial deploy of an app. Some apps need specific settings or deploy hooks only during the first deploy. The Boxfile.install allows for this. Once an app is launched, the Boxfile.install will no longer be honored.
Everything specified in the Boxfile.install is merged into your Boxfile on your initial deploy, so all settings in both the Boxfile.install and the Boxfile are honored. It isn't necessary to duplicate configurations in the two files. All subsequent deploys will ignore the Boxfile.install.
When creating and testing a Quickstart, we recommend including settings that would typically be in a Boxfile.install in the normal Boxfile. Once your Quickstart is tested and ready to go, move those settings into a Boxfile.install.
Build & Deploy Hook
Build & Deploy Hooks allow you to “hook” scripts into an app’s deploy process. They’re great for tasks such as modifying config files, database migrations, clearing caches, or anything else you can think up. The possibilities really are limitless. For full details, check out the Build & Deploy Hooks doc
Whenever a service is created on Pagoda Box, Environment Variables are automatically created for all necessary service connection credentials. By including environment variables in place of connection credentials in your code-base, your Quickstart will automatically and securely connect to any application services created on deploy. You can also include custom Environment Variables in your Boxfile.
Code, Test, Publish
Feel free to deploy and test your Quickstart as a Tinker App. That's why we offer them—to help make tinkering in a live environment easier. Once your Quickstart is ready for the world, create a new Quickstart on Pagoda Box it!
If you have any questions, suggestions, or corrections, let us know.