Deploying an Application

This tutorial will take you through the process of deploying an App to a production Rack.

Installation

Before we begin you will need to install a production Rack:

We recommend following the getting started guide and installing a Rack via the web console but you can optionally install a Rack using the command line Rack install instructions

Verify installation

Verify that your production Rack is running with convox rack:

$ convox rack
Name     production
Provider aws
Router   router.production.convox
Status   running
Version  3.23.3

Get an example application

Clone the NodeJS example

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

Enter the directory with the example application

$ cd nodejs

Look at the convox.yml

$ cat convox.yml

environment:
  - PORT=3000
services:
  web:
    build: .
    port: 3000

This convox.yml defines one Service named web that will be built from the Dockerfile in the repo. Each Process of this Service will listen on port 3000.

Deploy the application

First you will need to create an App:

$ convox apps create nodejs

Once this completes, you can deploy the code:

$ 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.96MB
Step 1/5 : FROM node:20-alpine
20-alpine: Pulling from library/node
e7c96db7181b: Pulling fs layer
50958466d97a: Pulling fs layer
56174ae7ed1d: Pulling fs layer
284842a36c0d: Pulling fs layer
...
Status: Downloaded newer image for node:20-alpine
---> b95baba1cfdb
Step 2/5 : WORKDIR /usr/src/app
---> 83aac0816456
Step 3/5 : COPY . /usr/src/app
---> 6c88d15e88c9
Step 4/5 : EXPOSE 3000
---> db735909e450
Step 5/5 : CMD ["node", "app.js"]
---> 7bd8ca94d031
Successfully built 7bd8ca94d031
Running: docker push registry.05456db021737ab6.convox.cloud/nodejs:web.BNLGVRXMCAP

Promoting RHQFJKRJNHJ...
2026-03-18T14:22:13Z system/k8s/atom/app Status: Running => Pending
2026-03-18T14:22:14Z system/k8s/web-749dd486d8 Created pod: web-749dd486d8-8v4ss
2026-03-18T14:22:14Z system/k8s/web-749dd486d8-8v4ss Successfully assigned nodejs/web-749dd486d8-8v4ss to production-node-3n6m6
2026-03-18T14:22:14Z system/k8s/web Scaled up replica set web-749dd486d8 to 1
2026-03-18T14:22:15Z system/k8s/atom/app Status: Pending => Updating
2026-03-18T14:22:16Z system/k8s/web-749dd486d8-8v4ss Pulling image "registry.05456db021737ab6.convox.cloud/nodejs:web.BNLGVRXMCAP"
2026-03-18T14:22:22Z system/k8s/web-749dd486d8-8v4ss Successfully pulled image "registry.05456db021737ab6.convox.cloud/nodejs:web.BNLGVRXMCAP"
2026-03-18T14:22:22Z system/k8s/web-749dd486d8-8v4ss Created container main
2026-03-18T14:22:22Z system/k8s/web-749dd486d8-8v4ss Started container main
2026-03-18T14:22:27Z system/k8s/atom/app Status: Updating => Running
OK

CLI commands that are specific to an app either take an -a appname option or can infer the app name from the name of the local directory; in this case nodejs

View the application in a browser

You can get the URL for your running services with the convox services command:

$ convox services
SERVICE  DOMAIN                                PORTS
web      web.nodejs.0a1b2c3d4e5f.convox.cloud  443:3000

In your browser navigate to the hostname shown for the web service. (i.e. https://web.nodejs.0a1b2c3d4e5f.convox.cloud/)

List the processes of the application

$ convox ps
ID                    SERVICE  STATUS   RELEASE     STARTED       COMMAND
web-0123456789-abcde  web      running  RBCDEFGHIJ  1 minute ago

View the application logs

$ convox logs
2026-03-18T14:22:30Z service/web/web-0123456789-abcde Node.js app listening on port 3000
2026-03-18T14:22:35Z service/web/web-0123456789-abcde GET / 200 3.241 ms
2026-03-18T14:22:36Z service/web/web-0123456789-abcde GET /favicon.ico 404 1.027 ms
2026-03-18T14:22:40Z service/web/web-0123456789-abcde GET / 200 0.892 ms

Notice that the prefix of each log line contains the time that it was received along with the name of the Service and the ID of the Process that produced it.

Use Ctrl-C to stop following the logs.

Scale the application

$ convox scale web --count=2
Scaling web...
2026-03-18T14:25:00Z system/k8s/web-0123456789-zwxwv Pulling image "registry.05456db021737ab6.convox.cloud/nodejs:web.BNLGVRXMCAP"
2026-03-18T14:25:03Z system/k8s/web-0123456789-zwxwv Successfully pulled image "registry.05456db021737ab6.convox.cloud/nodejs:web.BNLGVRXMCAP"
2026-03-18T14:25:03Z system/k8s/web-0123456789-zwxwv Created container main
2026-03-18T14:25:03Z system/k8s/web-0123456789-zwxwv Started container main
OK

Now try listing the processes again:

ID                    SERVICE  STATUS   RELEASE     STARTED        COMMAND
web-0123456789-abcde  web      running  RBCDEFGHIJ  2 minutes ago
web-0123456789-zwxwv  web      running  RBCDEFGHIJ  1 minute ago

Set an environment variable

$ convox env set TEST=hello
Setting TEST... OK
Release: RCDEFGHIJK

List the Releases to see your change:

$ convox releases
ID          STATUS  BUILD       CREATED         DESCRIPTION
RCDEFGHIJK          BABCDEFGHI  1 minute ago    env add:TEST
RBCDEFGHIJ  active  BABCDEFGHI  10 minutes ago  build 0a1b2c3d4e commit message

Promote the new release

Promoting a Release starts a rolling deployment:

$ convox releases promote
Promoting RCDEFGHIJK...
2026-03-18T14:30:00Z system/k8s/atom/app Status: Running => Pending
2026-03-18T14:30:01Z system/k8s/atom/app Status: Pending => Updating
2026-03-18T14:30:02Z system/k8s/web Scaled up replica set web-9876543210 to 2
2026-03-18T14:30:04Z system/k8s/web-9876543210-hijkl Started container main
2026-03-18T14:30:05Z system/k8s/web-9876542210-qrstu Started container main
2026-03-18T14:30:10Z system/k8s/web Scaled down replica set web-0123456789 to 0
2026-03-18T14:30:10Z system/k8s/web-0123456789 Deleted pod: web-0123456789-abcde
2026-03-18T14:30:10Z system/k8s/web-0123456789 Deleted pod: web-0123456789-zwxwv
2026-03-18T14:30:15Z system/k8s/atom/app Status: Updating => Running
OK

Running convox releases promote takes an optional release ID. Running without an ID will promote the latest Release.

Next steps

Learn more about deploying changes
Learn more about scaling
Create a review workflow to automatically create a review app every time you open a pull request
Create a deployment workflow to automatically deploy your app every time you merge to master
Browse Example Apps for ready-to-deploy sample applications in various languages and frameworks