How to Deploy Moleculer Applications to Vultr with Nanobox
Moleculer is a fast & powerful microservices framework for Node.js. Vultr is relatively new cloud provider (with tons of experience) that offers high-performance SSD servers in datacenters around the world. Its simple UI makes it easy to use and love.
In this article, I'm going to walk through deploying a Moleculer application to Vultr using Nanobox. Nanobox uses Docker to build local development and staging environments, as well as scalable, highly-available production environments on Vultr.
Before You Begin
If you haven't already, create a free Nanobox account and download Nanobox Desktop.
Setup A Moleculer Project
Prerequisite: This guide assumes you already have Node and NPM installed. If not, you can quickly install Node (which includes NPM) and return.
Where to start:
- I'm starting from scratch - Walks you through the process of installing Moleculer and creating a new app.
- I'm configuring an existing app - Assumes you already have Moleculer installed with an existing app.
Starting From Scratch
Install Moleculer, moleculer-cli
, and create a new app:
# install moleculer-cli and save it as a dependency
npm i -g moleculer-cli
# create a new app using the pug (formerly jade) templating engine
moleculer init project-simple nanobox-moleculer
# go through the setup guide changing any options you'd like, otherwise defaults
# are fine
# change into your new app and test it (optional)
cd nanobox-moleculer && npm run dev
Configure Your App
Nanobox uses a simple yaml config file called the boxfile.yml
to build and configure your app's environment.
Add a boxfile.yml
Create a boxfile.yml
in the root of your project with the following:
run.config:
engine: nodejs
extra_packages:
- nginx
web.main:
start:
nginx: nginx -c /app/etc/nginx.conf
moleculer: npm run start
data.redis:
image: nanobox/redis:3.2
NOTE: You may need to modify some boxfile configurations specific to your project (such as the database). You'll find more info on this in the docs and guides.
Test Your App Locally (optional)
Nanobox comes with a local development environment that allows you to run your app locally before you deploy it.
# (optional) add a DNS alias to access your app from the browser
nanobox dns add local moleculer.local
# start your app
nanobox run npm run dev
If you added a DNS alias, access your app at moleculer.local:3000. If not, you can access it via the IP provided in the console after you've started your server.
Whenever you exit out of the Nanobox console, it'll shut down your VM and drop you back into your host OS.
Configure Moleculer
IMPORTANT: Whether you created the application yourself or with the generator, there are three important pieces of configuration that every application must have:
- Your app must bind to all IP's (0.0.0.0). Why?
- Your app must listen on port 8080. Why?
- Your app must use environment variables (evars) to connect to Nanobox services. Why?
Moleculer binds to 0.0.0.0 by default, so no additional config is needed.
Update the Database Connection
When Nanobox spins up a database, it generates environment variables for the necessary connection credentials.
Moleculer is pretty free-form when it comes to configuring a database connection. However you choose to configure yours, you can access the following environment variables:
process.env.DATA_REDIS_HOST
process.env.DATA_REDIS_USER
process.env.DATA_REDIS_PASS
Create a Database Connection
Update the Redis connection in moleculer.config.js
as follows:
cacher: `redis://${process.env.DATA_REDIS_HOST}:6379`,
transporter: `redis://${process.env.DATA_REDIS_HOST}:6379`,
NOTE: Nanobox provides a default database named gonano
, but you're welcome to create your own. Also, Nanobox will always use a services default port when trying to connect, in this example 6379 for postgres
Prepare Moleculer for Deploy
It's recommended to use an Nginx reverse proxy to serve static assets. Most Node frameworks are compiled and served static.
Create an etc/nginx.conf
in your project with the following contents:
worker_processes 1;
daemon off;
events {
worker_connections 1024;
}
http {
include /data/etc/nginx/mime.types;
sendfile on;
gzip on;
gzip_http_version 1.0;
gzip_proxied any;
gzip_min_length 500;
gzip_disable "MSIE [1-6]\.";
gzip_types text/plain text/xml text/css
text/comma-separated-values
text/javascript
application/x-javascript
application/atom+xml;
# Proxy upstream to moleculer
upstream moleculer {
server 127.0.0.1:3000;
}
# Configuration for Nginx
server {
# Listen on port 8080
listen 8080;
# Settings to serve static files
location ^~ /static/ {
root /app/;
}
# Serve a static file (ex. favico)
# outside /static directory
location = /favico.ico {
root /app/favico.ico;
}
# Proxy connections to moleculer
location / {
proxy_pass http://moleculer;
proxy_redirect off;
proxy_set_header Host $host;
}
}
}
That's it! On to the main event, deploying your application!
Setup Your Vultr Account
If you haven't already, create a Vultr account. In your Vultr admin, select "Account" in the left-nav and open the "API" section. By default, Vultr API access is disabled. When you enable it, they will provide you with an API key.
Vultr lets you whitelist subnets that can access the Vultr API using the generated key. To use the Nanobox Vultr integration, go ahead and click "Allow All IPv4".
Note: If you're uncomfortable whitelisting all IPv4 addresses, you can whitelist 138.197.215.155/32
. This is the subnet on which the Nanobox Vultr adapter is hosted, but this subnet is subject to change. If/when it changes, you will need to manually update your Vultr account with the new subnet.
Add a New Provider to Your Nanobox Account
Select Vultr and click "Proceed."
Nanobox needs your Vultr access token to authenticate with your Vultr account. Paste in your token and click "Verify & Proceed."
Name your provider and choose a default region. The name is arbitrary and only meant to help you identify it in your list of provider accounts.
Launch a New App
Go to the home page of your Nanobox dashboard and click the "Launch New App" button. Select your Vultr provider from the dropdown and choose the region in which you'd like to deploy your app.
Confirm and click "Let's Go!" Nanobox will order a VC2 instance under your Vultr account. When the instance is up, Nanobox will provision platform components necessary for your app to run:
- Load-Balancer: The public endpoint for your application. Routes and load-balances requests to web nodes.
- Monitor: Monitors the health of your server(s) and application components.
- Logger: Streams and stores your app's aggregated log stream.
- Message Bus: Sends app information to the Nanobox dashboard.
- Warehouse: Storage used for deploy packages, backups, etc.
Once all the platform components are provisioned and running, you're ready to deploy your app.
Stage Your App Locally
Nanobox provides "dry-run" functionality that simulates a full production deploy on your local machine. This step is optional, but recommended. If the app deploys successfully in a dry-run environment, it will work when deployed to your live environment.
nanobox deploy dry-run
More information about dry-run environments is available in the Dry-Run documentation.
Deploy
Add Your New App as a Remote
From the root of your project directory, add your newly created app as a remote.
nanobox remote add app-name
This connects your local codebase to your live app. More information about the remote
command is available in the Nanobox Documentation.
Deploy to Your Live App
With your app added as a remote, you're ready to deploy.
nanobox deploy
Nanobox will compile and package your application code, send it up to your live app, provision all your app's components inside your live VC2 instance, network everything together, and BOOM! Your app will be live on Vultr.
Manage & Scale
Once your app is deployed, Nanobox makes it easy to manage and scale your production infrastructure. In your Nanobox dashboard you'll find health metrics for all your app's instances/containers. Your application logs are streamed in your dashboard and can be streamed using the Nanobox CLI.
Although every app starts out on a single VC2 instance with containerized components, you can break components out into individual servers and/or scalable clusters through the Nanobox dashboard. Nanobox handles the deep DevOps stuff so you don't have to. Enjoy!
Get in Touch
Additional Links
- boxfile.yml Documentation
- Scaling Documentation
- Live App Management
- General Documentation
- Language & Framework Guides
FAQ
Why 0.0.0.0
Nanobox uses Docker to containerize your application within its own private network. Using 127.0.0.1
or localhost
(the "loopback" IP) inside of a container will loopback to the container, not the host machine. In order for requests to reach your application, your application needs to listen on all available IP's.
Why Port 8080
Nanobox provides your application with a router that directs traffic through a private network created for your app. The router listens on ports 80 and 443, terminates SSL, and forwards all requests to port 8080.
Note: Your app/framework can listen on a port other than 8080, but you will need to implement a proxy that listens on 8080 and forwards to your custom port.
Why Use Environment Variables
Environment variables serve two purposes:
-
They obscure sensitive information in your codebase. Environment variables referenced in your code are populated at runtime, keeping potentially sensitive values out of your codebase.
-
Due to the dynamic nature of containerized applications, it's hard to predict the host IP of running services. These IP's are subject to change as your infrastructure changes. When creating your infrastructure, Nanobox knows what these values are and creates evars for necessary connection details.
Subscribe to Nanobox
Get the latest posts delivered right to your inbox