| title | draft | slug | url |
|---|---|---|---|
Introduction |
false |
Introduction |
/getting-started/introduction |
Convox is an open-source Platform as a Service (PaaS) that you can install on your own infrastructure.
Here are some helpful tutorials to get started with Convox:
- Create a Free Convox Account
- Install a Runtime Integration for Your Cloud Provider
- Install a Rack
- Install the Convox CLI and Log In
- Deploy a Sample App
- Make a Code Change and Redeploy
- Perform a Rollback
To create a Convox account, simply sign up here. We recommend using your company or organization's email address.
The first time you log in, you will be prompted to create an Organization. An Organization can have multiple users, such as colleagues or project collaborators, who you can invite to join. You can rename your Organization at any time from the Console Settings page.
Convox currently supports AWS, Google Cloud, Digital Ocean, and Microsoft Azure. To install a Convox Rack, you need a runtime integration. In the web console, click on the Integrations link, then click the plus sign in the Runtime section to select your cloud provider and create an integration. All integrations use a specific security role created for Convox, which can be removed at any time. Ensure you have an account with sufficient permissions, typically an administrator role, for your cloud provider.
Each time you install Convox, you create a new Rack.
A Rack is an isolated set of computing resources, network infrastructure, and storage that can contain one or more Apps. You can use multiple Racks to isolate different environments, customers, or business units.
Many users have two Racks: one for staging and one for production. You can also run a Rack on your local development workstation to develop your app in an environment nearly identical to production.
Once you have set up the runtime integration, it's time to create your first Rack! Click on the Racks link in the web console, then click the cloud Install button, select the runtime integration you just created, and install a Rack. Give your Rack a name like dev and select the region you want to install it in.
You can further customize your Rack configurations with Rack Parameters. To start, you can choose one of our predefined Rack Templates or fully customize your Rack to your needs. Unless specified, all Rack Parameters can be changed whenever you'd like, so with a single CLI command, you can change most overall configurations on the fly.
Finally, click install to begin creating your infrastructure. Rack installation typically takes between 5-20 minutes depending on the cloud provider. If you click on the Rack as it is being installed, you can follow along with the Rack creation progress.
To install the Convox CLI, follow the instructions for your operating system:
$ 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$ curl -L https://github.com/convox/convox/releases/latest/download/convox-linux-arm64 -o /tmp/convox
$ sudo mv /tmp/convox /usr/local/bin/convox
$ sudo chmod 755 /usr/local/bin/convox$ 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$ curl -L https://github.com/convox/convox/releases/latest/download/convox-macos-arm64 -o /tmp/convox
$ sudo mv /tmp/convox /usr/local/bin/convox
$ sudo chmod 755 /usr/local/bin/convoxOnce you have installed the CLI, you can log in to your Convox account by copying the login command from the Convox Console checklist/tour page.
If you ever need to log in to the CLI again, you can generate a new CLI key by going to the account page and clicking on reset button, which will generate a new key and login command.
Alternatively, if you have access to the CLI key and do not wish to reset it, you can run the following and enter your CLI key on the prompt:
$ convox login console.convox.com -t 0123456789abcdefghijklmnopqrstuvwxyzFor a quick overview of some commonly used CLI commands, check out this blog post on common Convox CLI commands.
One of the easiest ways to get familiar with Convox is to clone one of our sample apps. For this tutorial, we will use a simple Node.js app from our example repository.
$ git clone https://github.com/convox-examples/nodejs.git$ cd nodejs$ cat convox.yml
environment:
- PORT=3000
services:
web:
build: .
port: 3000This convox.yml defines a global Environment Variable named PORT and one Service named web. Each Process of this Service will listen on the specified port. This app is a simple example, but the options available for convox.yml allow you to specify very complex apps made up of many Services and Resources.
Before you can deploy for the first time, you need to create an empty App to deploy to.
First, verify that you are logged into your organization and able to connect to your Rack by listing the current Racks with the convox racks command:
$ convox racks
NAME PROVIDER STATUS
org/dev aws runningThen, connect to the Rack you just created with convox switch:
$ convox switch devNow, create an empty app in your Rack with convox apps create:
$ convox apps createBy default, the app will be created using the name of the current directory. If you wish to call your app something else, you can specify the name as an argument:
$ convox apps create [name]CLI commands specific to an app either take an
-a appnameoption or can infer the app name from the name of the local directory; in this case,nodejs.
$ 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
..........The first time you deploy a new app into a Rack can take a few minutes depending on the size of the app, but subsequent deploys will be much faster.
Once the deployment has completed, verify the app is running by running the convox services command in the terminal to get the URL(s) for all running services:
$ convox services
SERVICE DOMAIN PORTS
web web.nodejs.0a1b2c3d4e5f.convox.cloud 443:3000In your browser, navigate to the hostname shown for the web service.
Edit the file app.js in your local directory and modify the line that says:
res.end('Hello World!\nI\'m: ' ...to instead say:
res.end('Hello Convox!\nI\'m: ' ...Save the file, then re-deploy the app by running the deploy command again:
$ convox deployYou should notice that this deploy is much faster.
Once the deployment is complete, wait a few seconds and then reload your browser to see the new message.
One of the great features of Convox is nearly instantaneous rollbacks. Convox performs a rollback by maintaining the history and state of all previous Releases. You can view a list of all the releases for your app with the convox releases command:
$ convox releases
ID STATUS BUILD CREATED DESCRIPTION
RSBSSIPZIEF active BUTQJQRIWUZ 2 minutes ago
RYCWZIXLKQT BVXIJQDCELS 30 minutes agoYou can now roll back to your previous release with convox releases rollback:
$ convox releases rollback RYCWZIXLKQT
Rolling back to RYCWZIXLKQT... OK, RSPAOICEBER
Promoting RSPAOICEBER...
...Once the rollback is complete, refresh your browser, and you should see the Hello Convox! message has been reverted to Hello World!.
Hopefully, this small example has given you an idea of how easy and powerful Convox is. As a next step, let's get your first custom app configured and deployed by following the App Configuration Guide.
To get familiar with the Convox Console and some of its additional features, watch our Convox - Console Tour video on YouTube. This video provides a comprehensive overview of the console, helping you navigate and utilize its various functionalities effectively.