Skip to main content

​
Quickstart

This guide will walk you through installing Convox, setting up your first Rack, and deploying a sample application. You’ll learn the core workflow that you’ll use for all your deployments.
This tutorial uses Convox Cloud Console for the easiest getting started experience. You can also install Racks via the CLI - see Production Rack Installation for details.

​
Prerequisites

Before you begin, you’ll need:
  • A cloud provider account (AWS, Google Cloud, Digital Ocean, or Azure)
  • Admin-level permissions in your cloud account
  • Git installed on your local machine

​
Step 1: Create a Convox Account

1

Sign up for Convox

Create a free account at console.convox.com/signup. We recommend using your work email address.
2

Create an Organization

On first login, you’ll be prompted to create an Organization. This is a workspace where you can invite team members and manage your Racks and applications.You can rename your Organization anytime from the Console Settings page.

​
Step 2: Connect Your Cloud Provider

1

Navigate to Integrations

In the Convox Console, click Integrations in the sidebar.
2

Add Runtime Integration

Click the + button in the Runtime section and select your cloud provider.
3

Configure Permissions

Follow the provider-specific instructions to create a security role or service account for Convox. This allows Convox to provision infrastructure on your behalf.
Ensure you have administrator-level permissions in your cloud account to create the required IAM roles or service accounts.

​
Step 3: Install a Rack

A Rack is your Convox platform installation. It’s the foundation that hosts your applications.
1

Navigate to Racks

Click Racks in the Convox Console sidebar.
2

Create a New Rack

Click the Install button and select the Runtime Integration you just created.
3

Configure Your Rack

  • Name: Choose a name like dev, staging, or production
  • Region: Select a cloud region close to your users
  • Template: Start with a predefined template or customize parameters
Most Rack parameters can be changed after installation using convox rack params set. Start with defaults and optimize later.
4

Wait for Installation

Click Install to begin. Installation typically takes 5-20 minutes depending on your cloud provider.You can monitor progress by clicking on the Rack name during installation.

​
Step 4: Install the Convox CLI

The Convox command-line interface is your primary tool for deploying and managing applications. 
curl -L https://github.com/convox/convox/releases/latest/download/convox-macos -o /tmp/convox
sudo mv /tmp/convox /usr/local/bin/convox
sudo chmod 755 /usr/local/bin/convox

​
Authenticate the CLI

Copy the login command from the Convox Console checklist page, or generate a new CLI key from your account page. 
convox login console.convox.com -t YOUR_CLI_KEY_HERE
Verify your connection: 
$ convox racks
NAME               PROVIDER  STATUS
org/dev            aws       running

​
Step 5: Deploy a Sample Application

Let’s deploy a simple Node.js application to see Convox in action.
1

Clone the Example Repository

git clone https://github.com/convox-examples/nodejs.git
cd nodejs
2

Examine the Manifest

Take a look at the convox.yml file:
convox.yml
environment:
  - PORT=3000
services:
  web:
    build: .
    port: 3000
This manifest defines:
  • A global environment variable PORT set to 3000
  • A service named web that builds from the current directory
  • The service listens on port 3000
3

Switch to Your Rack

convox switch dev
This sets dev as your active Rack for subsequent commands.
4

Create the Application

convox apps create
By default, the app is named after the current directory (nodejs). To use a different name:
convox apps create myapp
5

Deploy the Application

$ convox deploy
Packaging source... OK
Uploading source... OK
Starting build... OK
Authenticating 782231114432.dkr.ecr.us-east-1.amazonaws.com: Login Succeeded
Building: .
Sending build context to Docker daemon  48.95MB
Step 1/5 : FROM node:10.16.3-alpine
...
Running: docker push 782231114432.dkr.ecr.us-east-1.amazonaws.com/convox:web.BUTQJQRIWUZ
Promoting RSBSSIPZIEF...
The first deployment takes a few minutes. Subsequent deployments are much faster due to Docker layer caching.
6

Access Your Application

Get the service URLs:
$ convox services
SERVICE  DOMAIN                               PORTS
web      web.nodejs.0a1b2c3d4e5f.convox.cloud  443:3000
Open https://web.nodejs.0a1b2c3d4e5f.convox.cloud in your browser. You should see “Hello World!”

​
Step 6: Make a Code Change

Let’s modify the application and redeploy to see Convox’s update workflow.
1

Edit the Code

Open app.js and change:
res.end('Hello World!\nI\'m: ' ...
to:
res.end('Hello Convox!\nI\'m: ' ...
2

Redeploy

convox deploy
Notice how much faster this deployment is! Convox reuses cached layers.
3

Verify the Change

Wait a few seconds for the rolling update to complete, then refresh your browser. You should see “Hello Convox!”

​
Step 7: Perform a Rollback

Convox makes rollbacks instant by maintaining the state of all previous releases.
1

List Releases

$ convox releases
ID           STATUS  BUILD        CREATED        DESCRIPTION
RSBSSIPZIEF  active  BUTQJQRIWUZ  2 minutes ago
RYCWZIXLKQT          BVXIJQDCELS  30 minutes ago
2

Rollback to Previous Release

$ convox releases rollback RYCWZIXLKQT
Rolling back to RYCWZIXLKQT... OK, RSPAOICEBER
Promoting RSPAOICEBER...
3

Verify the Rollback

Refresh your browser - the message should revert to “Hello World!”
Rollbacks use Kubernetes rolling updates, so there’s zero downtime. Your users won’t experience any interruption.

​
What’s Next?

Congratulations! You’ve successfully:
  • ✅ Installed a Convox Rack
  • ✅ Deployed an application
  • ✅ Made a code change and redeployed
  • ✅ Rolled back to a previous release
Now you’re ready to dive deeper:

Configure Your Own App

Learn how to add a convox.yml to your existing application

Add Resources

Set up Postgres, Redis, MySQL and other managed resources

Environment Variables

Manage secrets and configuration across environments

CI/CD Integration

Automate deployments with GitHub Actions, GitLab CI, and more

​
Common Commands

Here are the CLI commands you’ll use most often:
View Logs
convox logs -a myapp
convox logs -a myapp --filter web
convox logs -a myapp --since 10m
Run One-Off Commands
convox run web rails console -a myapp
convox run worker bundle exec rake db:migrate -a myapp
Scale Services
convox scale web --count 5 -a myapp
convox scale web --cpu 512 --memory 1024 -a myapp
Manage Environment Variables
convox env -a myapp
convox env set FOO=bar -a myapp
convox env unset FOO -a myapp

​
Getting Help

Documentation

Browse the complete Convox documentation

Stack Overflow

Ask questions and find answers from the community

GitHub Issues

Report bugs or request features

Common CLI Commands

Quick reference for frequently used commands

Build docs developers (and LLMs) love

Get started for freeTalk to us