Table of Contents
Things to Know When Coding a Quickstart
Tools to Use When Coding a Quickstart
Code, Test, Publish
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 guide 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, all controlled by a simple slider. 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 What You Need to Know About Pagoda Box Guide.
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 shared writable directories in the Boxfile, but these should be used sparingly, especially when creating a Quickstart. Any files stored within a directory specified as a shared writable will not be available after deploy. We create a network mount over writable 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. The network mount essentially hides any files stored within a shared writable directory. We recommend using shared writable directories for things like user-uploaded content, custom logs, and any other written content that need to stay in sync across web and worker instances.
No Auto-Installers
Many popular frameworks and web-applications use auto-install scripts which 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 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
The Boxfile is used to configure an app's environment on Pagoda Box — everything from shared writable directories, to php versions. For the full Boxfile documentation, check out the Understanding the Boxfile Guide.
A feature of the Boxfile that is incredibly useful when creating Quickstarts is Component Triggers. Basically, any component that is included in the Boxfile will automatically be created on deploy. This means you can launch databases, caches, and workers simply by including them in the Boxfile. Whenever a component is launched, Environment Variables are automatically created for all necessary component connection credentials, so if those variables are included in your codebase, the components will be instantly usable.
The Boxfile.install
The Boxfile.install is a Boxfile that is honored only on 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.
Note: Boxfile.install Workflow
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.
Deploy Hooks
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 Deploy Hooks Guide.
Environment Variables
Environment Variables allow your Quickstart to be fully functional immediately after deploy. Whenever a component is created on Pagoda Box, Environment Variables are automatically generated for each of the necessary connection credentials. By including server variables (ex. $_SERVER['DB1_USER']) in place of connection credentials in your code-base, your Quickstart will automatically and securely connect to any application components created on deploy. You can also include custom Environment Variables in your Boxfile.
Code, Test, Publish
Feel free to deploy and test your Quickstart on free resources. That's why we offer them—to help make development easier. Once your Quickstart is ready for the world, Publish it!