Vultr Marketplace

1. Create a vendor account and set your contact information.

2. Click the Marketplace icon at the bottom of the customer portal's left-hand menu.

3. Click Get Started Now.

4. Agree to the Marketplace Publisher Agreement.

5. Enter your Vendor Username.

6. Click the Vendor Settings tab.

7. Enter your Vendor contact information. All fields are optional.

8. Click Update Contact Information.

• Click the Create New App tab to create a Marketplace app, then fill in the data fields to describe your app.

  • App Name is the short name of your application.
  • Support URL is a link to your support web page.
  • Support Email is an address customers can use to contact you for help.
  • Operating System should include the distribution and version number.
  • Description is a one-line description of your application.
  • App Name ID Format is automatically generated from your App Name. You should not need to change it.
  • Leave the Repo URL field blank; it's unused.

Readme

The Readme information is visible to the public on your app's marketing page in the General Information tab, like this example for Minecraft. You should supply the introduction and marketing information here in Markdown format. You can upload images with copy/paste, drag-and-drop, or the upload image icon in the toolbar.

Uploading images through the editor stores them in Vultr Object Storage. For security reasons, if you link to outside images, they will not be displayed. Please upload your images through the editor to store them on Vultr's servers.

See our Markdown formatting tips for the Readme and App Instructions.

Click the Add App button, and you'll return to the Marketplace Applications list.

1. Click the application name to open the General Information tab of the Edit App screen.

2. Upload the image icons.

3. Select the application categories.

4. If you didn't enter a Readme in the previous step, you could update it here. See our Markdown formatting tips for the Readme and App Instructions.

5. Click the Update App button at the bottom of the screen.

1. Click the Support Information tab.

2. Enter the contact information and click Update App Support Info. All information is optional.

• To learn how to display variables in the application instructions, see Create the Application Instructions section.
• To learn how to use these variables in your deployment scripts, see Create Provisioning Scripts.

User-supplied Variable

1. Click the Variables tab.

2. Select User Supplied type.

3. Enter the required information.

   • Label: This is visible to the public. On public landing pages, there isn't a value available for the variable, so we show this label in its place. You may enter up to 255 characters.
   • Name: The variable name has a max length of 15 characters and must use Snake Case. Only lower-case and underscores are allowed.
   • Input Type: Choose Text Field or Textarea.
   • Required: Select if the variable is required.

4. After entering your variable information, click Add New Variable.

Password Variables

Similar to user-supplied variables, you can also create one or more uniquely generated passwords at each deployment with password variables. The system generates these automatically, and the user is not prompted to supply the value. Like user-supplied variables, you can show these in your application instructions and use them in deployment scripts.

1. Click the Variables tab.

2. Select Password type.

3. Enter the required information.

   • Label: This is visible to the public. On public landing pages, there isn't a value available for the variable, so we show this label in its place. You may enter up to 255 characters.
   • Name: The variable name has a max length of 15 characters and must use Snake Case. Only lower-case and underscores are allowed.
   • Length: The password length must be between 6 and 50 characters.

4. After entering your variable information, click Add New Variable.

1. Click the App Instructions tab.

2. Enter the customer instructions for your application in Markdown format.

3. If you created application variables, display those values here by placing them in backticks and double braces.

Variables are expanded when placed in double braces. Backticks are required for password variables to prevent special characters from being interpreted incorrectly as Markdown. For example, if your variable is named web_password, you can display the variable in your instructions like this:

`{{web_password}}`

In addition, you can display two standard variables, which always exist and do not need to be pre-defined:

• {{ip}} is the primary IPv4 for the instance.
• {{root_password}} is the root password.

The {{ip}} variable is a special case. It does not need to be guarded with backticks because IP addresses do not contain any characters that are interpreted as Markdown.

Here's an example instruction page that demonstrates correct Markdown formatting:

# Example Application

Your application is ready!

* Your server's IP address is: `{{ip}}`.
* The root password is: `{{root_password}}`.

Connect to your web server at [**https://{{ip}}/**](https://{{ip}}/).

* Your webserver username is: **demo**.
* Your webserver password is: `{{web_pass}}`.

The MySQL root password is: `{{db_pass}}`.

In addition to basic login and password information, you can upload images and provide hyperlinks to other resources.

1. Click the Gallery tab.
2. Click the Upload Graphic button and choose an image to upload.

After a successful upload, you'll see an image thumbnail in the Gallery tab.

The thumbnail has two control buttons: Set as main and Delete.

• Set as main: You should choose one gallery image as the Main image for the public landing page. Click the Set as main button to make the selection.

• Delete: Click the trashcan icon to delete the gallery image. Deletion is permanent. Deleted gallery images can not be recovered.

Start with a Small Filesystem

When a customer deploys a Marketplace app, Vultr can expand your app to fill the filesystem but cannot shrink it. It is recommended to use the marketplace-2c-2gb plan, which is specifically designed for marketplace applications. This plan includes 2 vCPUs, 2 GB of memory, and 8 GB of storage.

If you create a 20 GB Marketplace app, and the customer deploys an 80 GB subscription, Vultr will expand the app to fill the entire 80 GB filesystem. However, if you create an app with an 80 GB filesystem, customers cannot deploy the app on smaller Vultr instances. You should use the smallest possible filesystem for your app.

Install cloud-init

Vultr Marketplace uses cloud-init to initialize the instance with network addresses, passwords, and startup scripts. These operating systems have the correct version of cloud-init pre-installed if you use Vultr's images.

Canonical added support for Vultr in cloud-init version 21.2. Until this version is available in your OS repository, please install Vultr's cloud-init. Please see the install_cloud_init() function in our helper script on GitHub. For more information, see this example script, which installs cloud-init on an apt-based system, or follow the steps below.

RHEL, CentOS, and other yum-based distributions should install as follows.

# cd /tmp
# wget https://ewr1.vultrobjects.com/cloud_init_beta/cloud-init_rhel_latest.rpm
# yum install -y cloud-init_rhel_latest.rpm

Debian must use this version. Do not compile from source or install from the Debian repositories.

# cd /tmp
# wget https://ewr1.vultrobjects.com/cloud_init_beta/cloud-init_debian_latest.deb
# apt-get update -y
# apt-get install -y /tmp/cloud-init_debian_latest.deb

Ubuntu should use the universal build.

# cd /tmp
# wget https://ewr1.vultrobjects.com/cloud_init_beta/cloud-init_universal_latest.deb
# apt-get update -y
# apt-get install -y /tmp/cloud-init_universal_latest.deb

NetworkManager Note

Cloud-init may not correctly interface with NetworkManager on some distros, such as CentOS and RHEL. On these distributions, the network will not be configured correctly, and the boot process fails. If this occurs, disable NetworkManager, then install and enable the network-scripts package. NetworkManager must be disabled but does not need to be uninstalled.

Set the Vultr Kernel Option

The Marketplace requires the kernel option vultr on Bare Metal instances. It's optional for cloud deployment, but it's a best practice to make your application compatible with both VPS and Bare Metal deployments. If your application is based on one of Vultr's OS images, this kernel option may already exist.

Check the Kernel Option

• Check /etc/default/grub:

  console Copy

  # grep 'vultr' /etc/default/grub
  

  You may see vultr in the output:

  GRUB_CMDLINE_LINUX_DEFAULT="vultr"

If there is no vultr option, you must add it.

Add the Kernel Option

1. Edit /etc/default/grub

   console Copy

   # nano /etc/default/grub
   

2. Find the line starting with GRUB_CMDLINE_LINUX_DEFAULT and add vultr to the end.

   GRUB_CMDLINE_LINUX_DEFAULT="quiet splash vultr"

   Save the file and close the editor.

3. Update grub. Check the documentation for your distribution to determine the correct procedure. Ubuntu/Debian systems may use the update-grub utility.

   console Copy

   # update-grub
   

CentOS/RHEL

CentOS/RHEL systems may use this one-line solution to add the kernel option.

# /sbin/grubby --update-kernel=ALL --args vultr

Variable Names

Variable names are used in multiple places:

• The Edit App Variables screen.
• The Metadata API endpoint.
• The customer's Application Instructions.
• Your cloud-init provisioning scripts.

Provisioning Scripts and the Metadata API

The per-instance cloud-init script is a popular place to use these variables because it only runs once when the instance is first deployed. For example, create two variables in the Marketplace Portal:

• demo_password : A password for a user named demo.
• web_password : A password for a web server's basic authentication.

You can discover their values in your startup script through the Vultr Metadata API. The API endpoint is formed from the variable name in the format http://169.254.169.254/v1/internal/app-{variable_name}x. For example, a variable named demo_password is requested from the endpoint:

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

When making requests, you must pass METADATA-TOKEN: vultr in the request header. Here's a curl example:

curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-demo_password

Likewise, to request a variable named web_password:

curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-web_password

Here's a simple example that creates a demo user and reports the web password. Create a /var/lib/cloud/scripts/per-instance/provision.sh cloud-init script.

# nano /var/lib/cloud/scripts/per-instance/provision.sh

Paste the following:

#!/bin/bash
## Runs once-and-only-once at first boot per instance.
echo $(date -u) ": System provisioned." >> /var/log/per-instance.log

## Capture Marketplace Password Variables
DEMO_PASSWORD=$(curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-demo_password)
WEB_PASSWORD=$(curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-web_password)

## Create user
adduser demo --gecos "First Last,RoomNumber,WorkPhone,HomePhone" --disabled-password
## Set Password
echo demo:$DEMO_PASSWORD | chpasswd

## Report the Web Password
echo "The Web password is: $WEB_PASSWORD" > /root/web-password.txt

Make the script executable.

# chmod +x /var/lib/cloud/scripts/per-instance/provision.sh

This example creates a user account named demo with the unique password generated by the Marketplace variable demo_password. It also writes a file to /root/web-password.txt with the value of web_password.

In a real application, you might pass the values to a database or set HTTP Authentication on your web server.

Here's another example. Add the following to your /var/lib/cloud/scripts/per-instance/provision.sh script.

## Capture the Marketplace Password Variable.
DB_PASS=$(curl -H "METADATA-TOKEN: vultr" http://169.254.169.254/v1/internal/app-db_pass)

## Create an example database.
mysql -u root -e "CREATE DATABASE example_db;";

## Create an example user and set the password to Marketplace Password Variable $DB_PASS.
mysql -u root -e "GRANT ALL ON example_db.* TO 'example_user'@'localhost' IDENTIFIED BY '$DB_PASS' WITH GRANT OPTION;";

Assuming you declared a variable named db_pass on the Edit App Variables screen, this script creates an example database user with a random password. The password is available to you in the Metadata API, and it's shown to the customer on the application instructions page.

Blocking SSH During Provisioning

It's a best practice to disable SSH while your provisioning scripts run, then re-enable SSH when finished, particularly if they require a long time to complete. A user who logs in via SSH while your provisioning script is running could cause unexpected side effects. We recommend disabling the SSH service entirely while your script runs. If this is not possible, please consider blocking access with the OS firewall. The final step in the provisioning script should enable SSH if your application allows SSH access for customers.

How to Build an Imageless App from Vendor Data

1. Navigate to the Builds tab for your marketplace app.
2. Click the Build from Vendor Data button.
3. Select a base operating system for your app.
4. Enter your Vendor Data.
5. Click Build App Image.

After you've built the image, you can edit the Vendor Data script by selecting the actions menu and choosing Edit. Learn more about how to use Vendor Data scripts at cloudinit.readthedocs.io.

How to Build From a Snapshot

If you are building your Marketplace app from a snapshot, we strongly suggest optimizing the server first. Some steps to consider are:

• Remove old logs and temporary files.
• Uninstall unneeded software.
• Overwrite free disk sectors with zeros. This allows significant compression and makes customer deployment much faster.

You should adapt the suggested code snippets that follow based on your needs and your OS distribution.

Verify /tmp

Verify the /tmp directory exists and has the proper permissions.

# mkdir /tmp
# chmod 1777 /tmp

Update the Server

• For yum-based distributions:

  console Copy

  # yum update -y
  # yum clean all
  

• For apt-based distributions:

  console Copy

  # apt-get -y update
  # apt-get -y upgrade
  # apt-get -y autoremove
  # apt-get -y autoclean
  

Clean Temporary Files

• Clean the temporary directories.

  console Copy

  # rm -rf /tmp/*
  # rm -rf /var/tmp/*
  

• Clean SSH Keys.

  console Copy

  # rm -f /root/.ssh/authorized_keys /etc/ssh/*key*
  # touch /etc/ssh/revoked_keys
  # chmod 600 /etc/ssh/revoked_keys
  

• Clean the logs.

  console Copy

  # find /var/log -mtime -1 -type f -exec truncate -s 0 {} \;
  # rm -rf /var/log/*.gz
  # rm -rf /var/log/*.[0-9]
  # rm -rf /var/log/*-????????
  # echo "" >/var/log/auth.log
  

• Clean old cloud-init information.

  console Copy

  # rm -rf /var/lib/cloud/instances/*
  

• Clean the session history.

  console Copy

  # history -c
  # cat /dev/null > /root/.bash_history
  # unset HISTFILE
  

Update mlocate

Update the mlocate database.

# /usr/bin/updatedb

Wipe Random Seed

Wipe the random seed file.

# rm -f /var/lib/systemd/random-seed

Wipe Machine ID

Distributions that use systemd should wipe the machine identifier to prevent boot problems.

# rm -f /etc/machine-id
# touch /etc/machine-id

Clear login History

Clear the login log history.

# cat /dev/null > /var/log/lastlog
# cat /dev/null > /var/log/wtmp

Wipe Free Space

Wipe unused disk space with zeros for security and compression.

# dd if=/dev/zero of=/zerofile
# sync
# rm /zerofile
# sync

Discard Unused Filesystem Blocks

Not all Linux distributions support fstrim, but you may consider running this final step before making the snapshot.

# fstrim /

Halt and Power Down

Vultr can snapshot a running server, but you may prefer a clean shutdown. If so, consider halting and powering off the server before taking the snapshot.

# shutdown -h now

To power off:

1. Click your server name in the customer portal to open the server information page.
2. Click the Server Stop button in the upper left.

Make the Snapshot

1. Navigate to the Add Snapshot page in the Vultr Customer Portal.

2. Select your instance in the dropdown.

3. Enter a descriptive label

4. Click Take Snapshot. Wait a few minutes for the snapshot to complete.

5. Click the Builds tab.

6. Select the snapshot image you just created.

7. Click Build App Image. The Vultr Marketplace takes your snapshot and builds it into an App Image.

1. Click the Version link. Enter a version number to identify this image. Notice that the Status is Not Live.

   

2. Click the Actions icon.

   Choose an action:

   • Publish Image: Set the image to Lives status.
   • Delete Image: Remove this image from the application. This does not delete the associated snapshot.
   • Deploy Image: Test an image deployment before publishing it in Live status. Make sure to test your image before making the app public.

   To choose a different live version, use the Actions icon to unpublish the current Live image first.

1. Click the Settings tab.

2. Choose your Public URL Slug and public/private status. See more details below the example image.

URL Slug

The Public URL Slug is the final part of your application's landing page URL. If your application's slug is my-fantastic-app, then the full URL to your app's landing page is:

https://www.vultr.com/marketplace/apps/my-fantastic-app

You can choose your public URL slug with the following restrictions:

• The slug must be unique across all Marketplace Apps.
• The slug can only contain letters, numbers, or hyphens. It can not start or end with a hyphen.

For SEO purposes, we suggest using hyphens to separate words in your slug. If you are not the official maintainer of a project, we request you preface your slug with your vendor name. For example, If you are a vendor named Foo and you distribute a custom WordPress app, a good slug choice would be foo-wordpress.

Preview the Landing Page

After you set your public URL slug, you can preview the landing page.

1. Click the General Information tab.

2. Click the View Public Landing Page link in the Readme section to preview your application's landing page.

Make the App Public

Making your app public is the final publishing step. While an App is private, it is only visible to your account. A public app is visible to all Vultr customers. Make sure you've previewed your landing page and tested your app. When you are ready for customers to deploy your app:

1. Click the Marketplace icon at the bottom of the left-hand menu of the customer portal.

2. Click the Settings tab.

3. Click the Make Public button.

4. Your app will be submitted to Vultr for review. You'll see this while Vultr reviews your app.

Vultr team will test your application and either approve or request changes. Vultr conducts an assessment of all Marketplace applications before approval. You'll receive a notification by email when the app is approved.

Unpublish the App

If published, the button text changes to Make Private.

1. Click the Settings tab.
2. Click the Make Private button.

Delete an Application

This action is irreversible and deletes all Marketplace information about your application.

• You cannot recover a deleted app.
• Deleting an app prevents customers from deploying new instances.
• Deleting your app does not delete any customer deployments. All deployed instances continue to run until the customer destroys them.

If you are sure, delete the app.

1. Click the Settings tab.
2. Click Delete app.