How to Build an Example Vultr Marketplace Application

Updated on June 23, 2021
How to Build an Example Vultr Marketplace Application header image

If you are new to the Vultr Marketplace, please see the documentation overview to get started.

Introduction

This tutorial explains how to build and publish a Vultr Marketplace sample application. All the source code is available in our GitHub repository.

The sample application is an Ubuntu 20.04 server with MariaDB and Nginx. The deployment scripts create a sample database, a database user, and protect the web server with basic authentication. The web and database passwords use application variables to create unique passwords for each deployment.

Create an Application Profile

Follow these steps to create your vendor account and application profile.

  1. Edit your vendor settings.
  2. Create a new application profile.
  3. Edit the general information.
  4. Edit the support information.

Publish the Application Instructions

  1. When a customer deploys your application, the Marketplace provides them with the IP address and root password. In addition to these values, you can create custom application variables. For this tutorial, please create the variables db_pass and web_pass.

    Screenshot of app passwords

    See our guide, Vultr Marketplace Application Variables, for more details.

  2. Next, publish the instructions for the customer deployment page, and include your application variables. See our guide, Vultr Marketplace Application Instructions, for details.

    If you'd like to skip reading that article, use this Markdown for the application instructions.

     Connect to your new webserver at [http://{{ip}}/](http://{{ip}}/).
    
     * Username: `example_user`
     * Password: `{{web_pass}}`
    
     MariaDB is installed. SSH to the server to access the database.
    
         $ ssh root@{{ip}}
    
     * Database login: `example_user`
     * Database password: `{{db_pass}}`
  3. Add your application's gallery images. Your public landing page uses these images to showcase your application.

Build the Application

Now that the application profile and variables are defined, it's time to create the actual application. You'll need a macOS or Linux workstation with bash or zsh. We've also tested these scripts in Windows with WSL.

  1. Clone the vultr-marketplace GitHub repository to your workstation.

     $ git clone https://github.com/vultr/vultr-marketplace.git
  2. Install HashiCorp Packer.

  3. Verify your workstation's IP address is in your Vultr API access control list.

  4. Publish your API key.

     $ export VULTR_API_KEY=<Your API Key>
  5. If you desire a debug log, export these two variables:

     $ export PACKER_LOG=1
     $ export PACKER_LOG_PATH=packer.log
  6. Change to the sample app directory.

     $ cd vultr-marketplace/sample-app
  7. Use packer init to automatically download the Vultr Packer Plugin.

     $ packer init sample-app.pkr.hcl
  8. Use packer build to automatically deploy a server, prepare it, make a snapshot, and then destroy the original server.

     packer build sample-app.pkr.hcl

    Packer will create a snapshot in your Vultr account named Sample App <Date Time>.

  9. Assign the snapshot as the live image for your Vultr Marketplace app.

Provisioning Scripts

This example app uses two provisioning scripts.

Per-Instance Script

Packer installs a deployment script in the snapshot at /var/lib/cloud/scripts/per-instance/setup-per-instance.sh. You can see the script in GitHub here.

The script executes when the customer deploys the server. It runs only one time; it will not run at each reboot. When the script runs, it:

  • Logs the start date/time to /var/log/per-instance.log
  • Captures the marketplace variables db_pass and web_pass.
  • Creates a database.
  • Adds example_user to the database with the db_pass password.
  • Creates an Nginx password for example_user with the web_pass password.
  • Logs the end date/time to /var/log/per-instance.log

Notice the lines that capture the Marketplace Password Variables. They use curl to retrieve variables you'll define later in this guide. The URL endpoint names are based on the variable names you defined earlier in the format:

 http://169.254.169.254/v1/internal/app-{variable_name}

For example, you'll retrieve a variable named web_pass at this endpoint:

 http://169.254.169.254/v1/internal/app-web_pass

See our guide to learn more about Vultr Marketplace Variables and provisioning scripts.

Per-Boot Script

Packer also installs a per-boot deployment script in the snapshot at /var/lib/cloud/scripts/per-boot/setup-per-boot.sh. You can see the script in GitHub here.

The script executes on every boot of the server. When the script runs, it logs the date/time to /var/log/per-boot.log. You can modify this script as needed.

More about Provisioning Scripts

You can run other types of provisioning scripts in addition to these examples. See the cloud-init documentation for more information.

Test the Application

Your application is ready to test.

  1. Deploy your Marketplace application from the Marketplace Builds tab. Use the Deploy Image option.

    Screenshot of deploy image menu

    You'll be directed to the server deployment page of the Vultr customer portal, and your Marketplace image is automatically selected as the Server Type.

  2. After the app deploys, SSH to the instance as root. You'll find the root password on the server information page.

  3. Check the cloud-init provision script log. You should see entries with a recent date and time.

     # cat  /var/log/per-instance.log
     Mon 22 Mar 2021 07:46:04 PM UTC : System provisioning started.
     Mon 22 Mar 2021 07:46:04 PM UTC : System provisioning script is complete.
  4. Verify the Nginx password file exists, and the provisioning script created a password hash.

     # cat /etc/nginx/.htpasswd
     example_user:$apr1$aNHmyqo3$UdY5dt9YMy8B8XNATgEn6/
  5. Look up the website password on the server information page. You can also find the password in /root/web-password.txt

  6. Navigate to the website. The website will prompt you for a username and password. Enter the username example_user and the password shown on the server information page.

  7. Log into the database as example_user with the database password shown on the server information page. You can also find the password in /root/db-password.txt

     # mysql -u example_user -p
  8. Show the database list and verify the example_db exists.

     MariaDB [(none)]> SHOW DATABASES;
     +--------------------+
     | Database           |
     +--------------------+
     | example_db         |
     | information_schema |
     +--------------------+
     2 rows in set (0.000 sec)

Publish

If you can complete the tests, you are ready to publish the application. Because this is just a sample application, you won't actually publish it.

When you create an actual application, please see the Vultr Marketplace Publication Settings guide to set your URL slug and submit the application for review.

More Information

This guide is part of the Vultr Marketplace documentation. Please see the documentation overview for more information.