Getting Started with Convox Cloud

This guide walks you through setting up Convox Cloud and deploying your first application. You can also follow the guided onboarding process when you first login to the Convox Console.

Prerequisites

Before you begin, ensure you have:

• A Convox account (sign up at console.convox.com)
• The latest Convox CLI installed (version 3.19.0 or higher)
• An application with a Dockerfile ready to deploy

Step 1: Install the Convox CLI

If you haven't installed the CLI yet, follow these instructions for your operating system:

macOS

$ 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

Linux

$ curl -L https://github.com/convox/convox/releases/latest/download/convox-linux -o /tmp/convox
$ sudo mv /tmp/convox /usr/local/bin/convox
$ sudo chmod 755 /usr/local/bin/convox

Verify the installation:

$ convox version
client: 3.22.2

Step 2: Login to Convox

Generate a CLI token from the Console Account page and authenticate with your Convox account:

$ convox login console.convox.com -t <CLI Token> 
Authenticating with console.convox.com... OK

Step 3: Create Your First Machine

To create a machine:

1. Log into the Convox Console
2. Navigate to the Cloud Machines page
3. Click the "New Machine" button
4. Configure your machine:
   • Name: Choose a descriptive name (e.g., "my-first-machine")
   • Size: Select the appropriate size (start with Small for production apps)
5. Click "Create Machine"

Once created, verify your machine is available:

$ convox cloud machines
NAME               SIZE    REGION      STATUS   CREATED
my-first-machine   small   us-east-1   running  2 minutes ago

Step 4: Prepare Your Application

Clone the Convox Node.js example application:

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

This example includes:

• A simple Express.js application (app.js)
• Package configuration (package.json)
• Docker configuration (Dockerfile)
• Convox deployment configuration (convox.yml)

Step 5: Create & Deploy Your Application

Create your application on the machine:

$ convox cloud apps create my-app -i my-first-machine
Creating my-app... OK

Deploy your application:

$ convox cloud deploy -a my-app -i my-first-machine
Packaging source... OK
Uploading source... OK
Starting build... OK
Building: .
...
Build: BABCDEFGHI
Release: RABCDEFGHI
Promoting RABCDEFGHI... OK

Step 6: Access Your Application

Get the URL for your deployed application:

$ convox cloud services -a my-app -i my-first-machine
SERVICE  DOMAIN                                    PORTS
web      web.my-app.cloud.convox.com              443:3000

Visit the URL in your browser to see your running application.

Step 7: View Logs

Monitor your application logs:

$ convox cloud logs -s web -a my-app -i my-first-machine
2024-01-15T10:30:00Z service/web/abc123 App listening on port 3000
2024-01-15T10:30:15Z service/web/abc123 GET / 200

Step 8: Scale Your Application

Adjust the number of running processes:

$ convox cloud scale web --count 2 -a my-app -i my-first-machine
Scaling web... OK

Or enable autoscaling in your convox.yml:

services:
  web:
    build: .
    port: 3000
    scale:
      count: 1-3
      cpu: 250
      memory: 512
      targets:
        cpu: 70

Then redeploy:

$ convox cloud deploy -a my-app -i my-first-machine

Adding a Database

To add a managed database to your application, update your convox.yml:

resources:
  database:
    type: postgres
    provider: aws
    options:
      class: dev
      version: 17.5

services:
  web:
    build: .
    port: 3000
    resources:
      - database

Deploy the updated configuration:

$ convox cloud deploy -a my-app -i my-first-machine

The database connection URL is automatically injected as environment variables:

DATABASE_URL=postgres://username:password@host.name:5432/database
DATABASE_USER=username
DATABASE_PASS=password
DATABASE_HOST=host.name
DATABASE_PORT=5432
DATABASE_NAME=database

Production Database

For production workloads, use a larger class with Multi-AZ failover:

resources:
  database:
    type: postgres
    provider: aws
    options:
      class: small
      version: 17.5
      durable: true

services:
  web:
    build: .
    port: 3000
    resources:
      - database

Common Workflows

Setting Environment Variables

$ convox cloud env set API_KEY=secret DATABASE_URL=postgres://... -a my-app -i my-first-machine
Setting API_KEY, DATABASE_URL... OK
Release: RCDEFGHIJK

Running One-Off Commands

$ convox cloud run web "npm run migrate" -a my-app -i my-first-machine
Running... OK

Viewing Releases

$ convox cloud releases -a my-app -i my-first-machine
ID           STATUS  BUILD        CREATED        DESCRIPTION
RCDEFGHIJK           BABCDEFGHI   1 minute ago   env add:API_KEY
RABCDEFGHI   active  BABCDEFGHI   5 minutes ago  

Rolling Back

$ convox cloud releases rollback RABCDEFGHI -a my-app -i my-first-machine
Rolling back to RABCDEFGHI... OK

Database Console

$ convox cloud resources console database -a my-app -i my-first-machine
psql (17.5)
Type "help" for help.
database=#

Best Practices

1. Start Small: Begin with an X-Small or Small machine and scale up as needed
2. Use Environment Variables: Never hardcode secrets in your code
3. Monitor Resources: Keep an eye on CPU and memory usage to right-size your machine
4. Enable Autoscaling: Let Convox automatically adjust capacity based on load
5. Use Cloud Databases for Production: Enable durable: true for high availability

Troubleshooting

Build Failures

If your build fails, check the build logs:

$ convox cloud builds logs BUILD_ID -a my-app -i my-first-machine

Application Won't Start

Verify your application processes are up:

$ convox cloud ps -a my-app -i my-first-machine

Check service logs:

$ convox cloud logs -s my-service -a my-app -i my-first-machine

Out of Resources

If you see resource errors, consider upgrading your machine size:

1. Log into the Convox Console
2. Navigate to your machine settings
3. Select a larger size
4. Apply the changes

Database Connection Issues

Verify the database is linked:

$ convox cloud resources -a my-app -i my-first-machine

Check environment variables:

$ convox cloud env -a my-app -i my-first-machine

Next Steps

• Machine Management - Detailed guide to machine configuration
• Cloud Databases - Database configuration and options
• CLI Reference - Complete command documentation
• Sizing and Pricing - Optimize your costs
• Limitations - Understand platform constraints

Getting Help

If you encounter issues:

• Check the documentation
• Visit the community forum
• Contact support at cloud-support@convox.com