Express Quickstart Guide

This guide will show you how to set up a Node.js app using the Express framework and the Mongoose ODM for MongoDB. This guide leverages Dockerfile Deploy.

Create an App

Tell Aptible that you want to provision an App. Until you push code and trigger a build, Aptible uses this as a placeholder.

To create an App, use the Dashboard, or the aptible apps:create command:

# Set or substitute $APP_HANDLE with the app name of your choice

aptible apps:create "$APP_HANDLE"

Aptible will provide your App's Git Remote in return. Copy it, you'll need it later.

Going forward in this document, we'll refer to the App's handle as $APP_HANDLE, and its Remote as $GIT_REMOTE.

Provision a Database

Start by adding a MongoDB Database for your App:

aptible db:create "$DB_HANDLE" --type mongodb

Make sure you set or substitute $DB_HANDLE with the database name of your choice (alternatively, you could use the Dashboard to create a Database as well).

The aptible db:create will return a connection string on success. This is a Database Credential. You'll need it later to configure your App.

Going forward in this document, we'll refer to the Credential as $DATABASE_URL.

📘

Note

Databases are only reachable from within your Stack's internal network.

This means your Containers will be able to connect to your database, but if you want to connect from your workstation, you'll need to use a Database Tunnel.

Add a Dockerfile

The Dockerfile is a text file that contains the commands you would otherwise execute manually to build a Docker image. Aptible uses the resulting Image to run Containers for your App.

A few guidelines:

1. The file needs to be called Dockerfile, starting with a capital letter, and no extension.
2. Place the Dockerfile at the root of the repository.
3. Be sure to commit them to version control.

Here is a sample Dockerfile for an Express app:

FROM node:8.2

ADD package.json /app/
WORKDIR /app
RUN npm install --production

# If you use Bower, uncomment the following lines:
# RUN npm install -g bower
# ADD bower.json /app/
# RUN bower install --allow-root

ADD . /app

# Run any additional build commands here...
# RUN grunt some:task

# Make sure your app is listening on port 3000
ENV PORT 3000
EXPOSE 3000

CMD ["node", "server.js"]

📘

Tip

See Optimizing Dockerfile caching for NPM to better understand this Dockerfile.

Configure Mongoose and Express

In server.js, configure Mongoose to read the MongoDB connection URL from a variable named DATABASE_URL.

var mongoose = require("mongoose");
mongoose.connect(process.env.DATABASE_URL);

Also, make sure Express is listening on the port exposed by the image built using the above Dockerfile (see Container Port for why this matters):

app.listen(process.env.PORT || 3000);

Bring it all together

At this point, you're almost ready to deploy.

All that is left to do is put the pieces together by configuring your App to point it to your Database, then you'll be ready to push your code to Aptible.

To add the required environment variables, use the aptible config:set command as documented below. Make sure you set or substitute $APP_HANDLE and $DATABASE_URL with their proper values.

aptible config:set --app "$APP_HANDLE" \
    "DATABASE_URL=$DATABASE_URL"

Once you're done, push your code to Aptible by adding Aptible as a git remote for your app, and then using git push to push your code:

git remote add aptible "$GIT_REMOTE"
git push aptible master

Deploy logs will stream to your terminal. They'll be useful in case anything goes wrong to understand the cause of the failure.

Add an Endpoint

At this point, your App is running on Aptible. What's next is expose it on the Internet!

Follow the instructions here to proceed: How do I expose my web app on the Internet?.

Meteor Quickstart Guide

This guide will show you how to set up a Node.js app using the Express framework and the Mongoose ODM for MongoDB. This guide leverages Dockerfile Deploy.

Create an App

Tell Aptible that you want to provision an App. Until you push code and trigger a build, Aptible uses this as a placeholder.

To create an App, use the Dashboard, or the aptible apps:create command:

# Set or substitute $APP_HANDLE with the app name of your choice

aptible apps:create "$APP_HANDLE"

Aptible will provide your App's Git Remote in return. Copy it, you'll need it later.

Going forward in this document, we'll refer to the App's handle as $APP_HANDLE, and its Remote as $GIT_REMOTE.

Provision a Database

Start by adding a MongoDB Database for your App:

aptible db:create "$DB_HANDLE" --type mongodb

Make sure you set or substitute $DB_HANDLE with the database name of your choice (alternatively, you could use the Dashboard to create a Database as well).

The aptible db:create will return a connection string on success. This is a Database Credential. You'll need it later to configure your App.

Going forward in this document, we'll refer to the Credential as $DATABASE_URL.

📘

Note

Databases are only reachable from within your Stack's internal network.

This means your Containers will be able to connect to your database, but if you want to connect from your workstation, you'll need to use a Database Tunnel.

Add a Dockerfile

The Dockerfile is a text file that contains the commands you would otherwise execute manually to build a Docker image. Aptible uses the resulting Image to run Containers for your App.

A few guidelines:

1. The file needs to be called Dockerfile, starting with a capital letter, and no extension.
2. Place the Dockerfile at the root of the repository.
3. Be sure to commit them to version control.

Here is a sample Dockerfile for a Meteor app:

FROM ubuntu:16.04

# Install Meteor dependencies
RUN apt-get update \
 && apt-get install -y curl procps python build-essential git \
 && rm -rf /var/lib/apt/lists/*

# Install Meteor
RUN curl https://install.meteor.com/ | sh
ENV METEOR_ALLOW_SUPERUSER=1

# Install Meteor build dependencies
ADD package.json /app/
WORKDIR /app
RUN meteor npm install

# Build app
ADD . /app
RUN meteor build --directory .

# Install App runtime dependencies
WORKDIR /app/bundle/programs/server
RUN meteor npm install

ENV PORT 3000
EXPOSE 3000

CMD ["meteor", "node", "boot.js", "program.json"]

Bring it all together

At this point, you're almost ready to deploy.

All that is left to do is put the pieces together by configuring your App to point it to your Database, then you'll be ready to push your code to Aptible.

To add the required environment variables, use the aptible config:set command as documented below. Make sure you set or substitute $APP_HANDLE and $DATABASE_URL with their proper values.

On variable deserves a little more attention here: ROOT_URL. This variable must be set to the URL where you plan to expose your app. For example, if your domain is www.example.com, you should set ROOT_URL to https://www.example.com.

aptible config:set --app "$APP_HANDLE" \
    "MONGO_URL=$DATABASE_URL" \
    "ROOT_URL=$ROOT_URL"

Once you're done, push your code to Aptible by adding Aptible as a git remote for your app, and then using git push to push your code:

git remote add aptible "$GIT_REMOTE"
git push aptible master

Deploy logs will stream to your terminal. They'll be useful in case anything goes wrong to understand the cause of the failure.

📘

Tip

You'll probably want to set MONGO_OPLOG_URL as well later on. Review the Meteor documentation accordingly.

Add an Endpoint

At this point, your App is running on Aptible. What's next is expose it on the Internet!

Follow the instructions here to proceed: How do I expose my web app on the Internet?.

For a Meteor app, you'll have to make sure the Custom Domain you use for your Endpoint matches the ROOT_URL you set earlier (you can also update ROOT_URL via aptible config:set).