Deploying to Vapor Cloud 2 Tutorial [FREE]

You’re ready to deploy that Vapor app you’ve worked so hard on. But how can you deploy it to a cloud solution, with minimum hassle? Vapor Cloud to the rescue!

Vapor Cloud 2 is a Platform as a Service (PaaS) built by the Vapor team specifically for hosting Vapor applications. In this tutorial, you’ll learn how to deploy your application to Vapor Cloud 2.

Vapor Cloud 2 is designed to simplify configuring servers and managing deployments so you can concentrate on writing code. Vapor Cloud 2 is still in pre-release, but it’s available to use for testing the deployment of your apps. And there’s some great news in this latest iteration: Vapor Cloud 2 provides a free database tier for persisting data! You can find out more about the release schedule of Vapor Cloud 2 here .

You’ll use a pre-built Vapor app named TIL (Today I Learned) that hosts user-supplied acronyms.

The high-level steps you’ll perform in this tutorial are:

• Setting up a Vapor Cloud account.
• Setting up Git access to the Vapor Cloud Git server.
• Forking a pre-built Vapor app on GitHub.
• Creating and setting up a new Vapor Cloud application for your app.
• Deploying your app to Vapor Cloud and bringing it online.

Note : This tutorial assumes you have some experience with using Vapor to build web apps. See Getting Started with Server-side Swift with Vapor if you’re new to Vapor. This tutorial also assumes you have some experience working with the command line, SSH, Docker, Git, and GitHub.

Getting Started

Click the Download Materials button at the top or bottom of this tutorial to download a text file in which you’ll keep track of all the credentials you’ll create in this tutorial.

You’ll also need a Vapor Cloud account in order to deploy your app. If you don’t have one, sign up for one here .

Once you’ve confirmed your email account and logged in to Vapor Cloud, you’ll see the Dashboard , which is still under construction at the time of writing this tutorial.

Setting Up Git Access

To host your code, you’ll need to access Vapor Cloud’s private Git server. The best way to do this is by adding your public SSH key to your new account.

On macOS, in Terminal , enter this command to find the file that contains your public SSH key:

ls ~/.ssh

Your file probably has one of the default public key filenames: id_rsa.pub , id_dsa.pub , id_ecdsa.pub or id_ed25519.pub .

Note : If you don’t have an SSH key, follow GitHub’s instructions to create one.

Copy the name of the id_something.pub file, and paste it into the following command:

pbcopy < ~/.ssh/<your .pub file>

This copies your public SSH key to the clipboard.

Now go to Settings in the Vapor Cloud console, and click the + button in the upper right corner to add your SSH key:

Give the key a name, paste the key in, then click Create . To verify your access, enter the following command in Terminal :

ssh [email protected]

Enter yes if it asks “Are you sure you want to continue connecting (yes/no)?”.

If your SSH key is working, you’ll see output similar to this:

PTY allocation request failed on channel 0
Hi [email protected], You've successfully authenticated to Vapor Cloud Git
Connection to git.code.vapor.cloud closed.

Forking the TIL Project

Rather than start from scratch, you’ll fork an existing Vapor app, and work on your fork for the rest of this tutorial.

The Vapor TIL app is available in a public repo on GitHub .

Running the app locally looks like this:

To work with your own version of this app, fork the repo to your own GitHub account:

Next, create a local clone of the repo on your development machine by cloning the repo fork from your account. In Terminal , cd to the directory where you want your local repo to live.

Then, if you’ve set up your GitHub profile with SSH , enter this command:

git clone [email protected]:<YOUR_GITHUB_USERNAME>/vapor-til.git

If you haven’t set up SSH access, you should clone the repository with HTTPS :

git clone https://github.com/<YOUR_GITHUB_USERNAME>/vapor-til.git

At this point, you want to ensure you have the version of the code that matches this tutorial. To make sure of this, execute the following commands against your local repo:

git reset --hard 3b7ead6
git push --force origin master

Doing this resets your fork to the particular commit you need for this tutorial.

Editing web.Dockerfile

Vapor Cloud uses Docker to build and run your app, and to handle HTTP requests on port 80. For this to happen, you’ll need to include a web.Dockerfile in the root folder of your project. web.Dockerfile sets up everything your app needs to run in a Docker container, including setting the Swift version and OS for the container. A number of prefabricated files are available at https://github.com/vapor-cloud/docker .

For the Vapor TIL app, you need the Swift version of web.Dockerfile . The root folder of the Vapor TIL app already contains this file. However, you need to make two changes to the template version of the file to work with your app.

Edit your local copy of web.Dockerfile and uncomment the following two lines:

COPY --from=builder /app/Public ./Public
COPY --from=builder /app/Resources ./Resources

This tells the app to load resources from the Public directory, and also sets up your Vapor app to use Leaf templating when deploying to the cloud.

Once you’ve made these changes, push your local version of web.Dockerfile to your GitHub fork. Open web.Dockerfile in your Github repo, to verify that your changes made it there.

With your fork of the app in place, you now need to create an Application on Vapor Cloud for your app.

Creating a New Vapor Cloud Application

Select Applications in the Vapor Cloud menu and click the + button in the upper right:

Choose a Generated name, to let Vapor Cloud generate an app name and app-slug for your application. Choose Dev Free for the Plan , and choose the only available Region for your server.

Click Create , and the Applications screen will display your new cloud application:

In this case, the app-slug is rain-dark-71923 . Store this value in creds.txt , and use this value whenever this tutorial specifies YOUR_APP_SLUG .

Setting Up Your Database

Version 2 of Vapor Cloud provides a free database tier for your cloud apps. The Vapor TIL app uses PostgreSQL for persistence, so you’ll add support for it to your cloud app now.

Click the + button in the upper right to open the New Service menu, and choose Database .

Then set up your database as follows:

Set Plan to Dev free : This opens the Engine field. Choose PostgreSQL 10.5 for the database engine, set the Region , then click Create .

You’ll see the new database instance running as part of your cloud app.

Note : This tutorial uses the default production environment for your new cloud application, but the Environment item under the + button menu lets you add more environments that you might need for other purposes, such as staging .

Setting Up Vapor’s Git Server

Next, you need to set up Vapor’s private Git server as a remote for your project. Click the highlighted More button on the Git card, then click Setup Instructions :

You’ll see two variations of the instructions:

Use the Existing Project instructions to set up Vapor Cloud as a new remote for your project:

git remote add cloud [email protected]:YOUR_APP_SLUG.git
git push cloud master

The Vapor TIL app uses Google and GitHub for authentication, and also uses SendGrid for sending registration emails. Third-party services like these typically provide security keys to use for your app, and it’s a best practice to not include such keys in your app’s source code, but instead provide them as environment variables on your server instance. So, you need to configure the environment variables in Vapor Cloud for use with your app.

Configuring OAuth Credentials

First, you’ll get a SendGrid API key . In the rest of this section, you’ll see how to determine the environment variables for Google and GitHub authentication. You’ll then configure all these environment variables for your cloud app.

Getting Your SendGrid API Key

In your browser, open SendGrid , sign up for a Free account, then click the link in the verification email.

Click Start for the Integrate using our Web API or SMTP relay option:

Then Choose Web API :

On the next page, it doesn’t matter which language you choose. I chose cURL , because, well, cURL.

Finally, enter a name for your API key, and click Create Key . Store this key in creds.txt .

Setting Up Google OAuth

To use Google OAuth in your application, you must first register the application with Google. In your browser, open Google APIs Credentials .

If this is the first time you’ve used Google’s credentials, the site will prompt you to create a project:

Note : You might have to widen your browser window to see the Create button, as the button hovers on the right edge of the screen.

Click Create to create a project for the TIL application. Fill in the form with an appropriate name like Vapor TIL :

Click Create , and you’ll return to the Credentials page. Click Create Credentials , and choose OAuth client ID :

Note : If you’d already created other projects in the past, click Select , and choose the project you just created.

Next, click Configure consent screen to set up the page that Google will present to users so they can authorize access to their details for your application.

Add your product or application name, Vapor TIL , then scroll down to Authorized domains . Enter v2.vapor.cloud , then click Save :

This takes you to the next step: Create OAuth client ID . Choose Web application , and add an Authorized redirect URI for testing your application — http://localhost:8080/oauth/google .

This is the URL that Google redirects back to once users have allowed your application access to their data.

But you also you want to deploy your application to the internet, just as you are doing here with Vapor Cloud 2. Therefore, you’ll need to add another redirect for the URL for that site, using your app-slug: https://YOUR_APP_SLUG.v2.vapor.cloud/oauth/google .

Store this URL in creds.txt as GOOGLE_CALLBACK_URL .

Click Create , and the site will provide you with you your client ID and client secret:

Store these credentials in creds.txt .

Note : You must keep these credentials safe and secure. Your secret provides access to Google’s APIs, and you absolutely must not share those credentials or keep your secret under source control. You should treat it, in effect, just as you would treat any of your passwords.

Setting Up GitHub OAuth

To use GitHub OAuth in your application, you must first register the application with GitHub. Fortunately, this process will go a little faster than it did when setting things up under Google.

In your browser, go to GitHub Developer settings . Click Register a new application :

Fill in the form with an appropriate name like Vapor TIL . Set the Homepage URL to https://YOUR_APP_SLUG.v2.vapor.cloud for this application, and provide a sensible description. Set the Authorization callback URL to https://YOUR_APP_SLUG.v2.vapor.cloud/oauth/github . This is the URL that GitHub redirects your users to, once they have authorized access to their data.

Store this URL in creds.txt as GITHUB_CALLBACK_URL .

Click Register application . After GitHub creates the application, you’ll be taken back to the application’s information page, where you’ll see the client ID and client secret that you need:

Store these credentials in creds.txt

Note : Again, you must keep these keys safe and secure. Your secret allows you access to GitHub’s APIs, and you should not share or check the secret into source control. Treat any API key or secret like a password.

Configuring Vapor Cloud Environment Variables

Having obtained your Google, GitHub, and SendGrid keys, you now need to configure them for your Vapor Cloud application.

Click the highlighted More button on the Application card:

Then click Config Vars :

Now copy and paste the keys and values from creds.txt , except for the “Vapor Cloud app-slug”, to set up the environment variables for your app. Be careful not to click anywhere outside the Config Vars window until you’ve clicked the Update button, or you’ll have to start over.

You’ve pushed your application code to the Vapor Cloud private Git server, and you’ve fully configured your app for deployment. It’s time to deploy your app to Vapor Cloud!

Deploying the Vapor Cloud App

To start the deployment, click the Deploy button on the Git card:

Use the Default Branch and click Deploy :

Be sure to note the comment on the deploy card that “Deployments usually take around 10 minutes to complete. They cannot be canceled.” Time for a celebratory drink or a brisk walk around the block!

While you’re celebrating, your app will build and be deployed to Vapor Cloud:

Upon your return, at the bottom of the window, you’ll see:

-----> Released v4
Pushed to Vapor Cloud on YOUR_APP_SLUG.v2.vapor.cloud
Job done: closing logs.
Activity closed, goodbye.
-----> Connection to logs closed

Bringing the App Online

With the app deployed for the first time, you must use one or more replicas to scale the app. You will not need to scale on subsequent deployments.

Click Scale on the web Replica card, then change 0 to 1 , and click Scale :

Once the scaling is done, point your browser at YOUR_APP_SLUG.v2.vapor.cloud .

You’ve just deployed your first Vapor app to Vapor Cloud 2!

Where to Go From Here?

You’ve seen how easy it is to host your Vapor app on Vapor Cloud 2. You learned how to set up the app using the Vapor Cloud 2 console, configure your Git repository, add the necessary configuration values to your application, and deploy your app.

You can learn much more about deploying to Vapor Cloud 2 in the official docs .

Remember that, at the time of writing this tutorial, Vapor Cloud 2 is still in pre-release, so be sure to follow its development schedule before you start hosting production apps on the service.

You’ll also want to learn about other deployment options for Vapor apps, such as Heroku. You can read about these other options in our book, Server Side Swift with Vapor , that covers everything you need to know to get started developing and deploying Vapor APIs and web apps.

Feel free to add comments or questions in the forum below!