Introduction
This guide walks you through common Convox commands used in a typical rack and application lifecycle.
It is designed to help you understand how to use Convox more effectively by detailing command options and contexts. Running the command convox by itself will list all available commands, providing a broad overview of your options. Additionally, you can append the --help option to any command to get more detailed information about its usage. Whether you're deploying applications, managing racks, or configuring settings, this guide provides the insights needed to navigate and utilize Convox commands proficiently. Learn how to target your commands correctly and manage your deployments with ease, ensuring a smooth operational flow across your projects.
Understanding Convox Command Contexts and Options
Convox commands are versatile and can be executed globally, at the rack level, or at the app level, depending on the scope of the action required:
- Global Level: Commands that apply across all environments.
- Rack Level: Commands that are specific to a single rack. You can specify the target rack by using the -r rackName option. If you have previously used convox switch rackName, this rack becomes your active rack, and you do not need to include the -r rackName option for further commands within this rack. However, you can still use -r rackName to target commands to a different rack, even when switched to another.
- App Level: Commands that are specifically targeted at an application within a rack. When executing these commands, you must specify the application using the -a appName option. If you are operating within the application's directory and this directory's name matches the application name, Convox assumes you are referring to that application, and you can omit the -a appName option.
By understanding these levels and options, you can more effectively manage your infrastructure and application deployments with Convox. This guide aims to clarify how to target your commands accurately to ensure they affect the intended scope of your Convox environment.
Note: All examples provided in this guide include the full -a appName and -r rackName options for the sake of clarity and information.
Convox CLI Setup
These commands involve setting up and updating the Convox CLI.
convox login
Authenticate with the Convox Console using your login token. You can generate a new token from your Console Account Page.
$ convox login console.convox.com -t a1234567-acde-1234-abcde-123abc456def
Authenticating with console.convox.com... OK
convox version
Check the current version of the Convox client and the current selected rack.
$ convox version
client: 3.18.0
server: 3.18.1
convox update
Update the Convox CLI to the latest version.
$ sudo convox update
Updating to 3.18.1... OK
Rack Configuration
Commands related to managing and switching between Convox racks.
convox racks
List all available racks.
$ convox racks
NAME PROVIDER STATUS
my-organization/demo-rack aws running
convox switch
Switch to a specific rack. Once switched to a rack you will not need to add the -r rackName flag to commands to target the rack.
$ convox switch demo-rack
Switched to my-organization/demo-rack
convox rack
Display detailed information about a rack.
$ convox rack -r demo-rack
Name demo-rack
Provider aws
Router router.3f031abdcc84be6b.convox.cloud
Status running
Version 3.18.1
convox rack params
View parameters of the current rack. You can find the full list and details for rack parameters for each cloud provider in our documentation: AWS | GCP | Azure | Digital Ocean
$ convox rack params -r demo-rack
region us-east-1
release 3.18.1
convox rack params set
Set a specific parameter for the rack. Some parameter changes require node recreation; this can take up to 10 minutes for the parameter to take effect. You can monitor the update status in the Update tab on the Convox Console after selecting your rack. Once updated, you can verify that the parameter is set by running convox rack params -r rackName.
$ convox rack params set build_node_enabled=true -r demo-rack
Updating parameters... OK
convox rack kubeconfig
Generate kubeconfig for the current rack and save it locally. This allows for kubectl commands to be sent directly to the rack's k8s cluster. By doing this, you gain direct command-line access to manage Kubernetes resources, enhancing your ability to perform detailed operations and troubleshooting.
$ convox rack kubeconfig -r demo-rack > ~/.kube/config
Application Management
These commands cover the lifecycle of applications from creation to deployment.
convox apps create
Create a new application. You can specify the application name immediately following the command. If no name is provided, the name of your local directory will be used by default.
$ convox apps create nodejs -r demo-rack
Creating nodejs... OK
convox deploy
Deploy an application. The deployment process involves packaging, uploading the source, and building the application.
$ convox deploy -a nodejs -r demo-rack
Packaging source... OK
Uploading source... OK
Starting build... OK
...
2024-05-01T03:44:01Z system/k8s/atom/app Status: Updating => Running
OK
convox apps
List all applications and their status in the rack. This command allows you to quickly view a snapshot of each application's deployment state within your active or specified rack.
$ convox apps -r demo-rack
APP STATUS RELEASE
nodejs running RVTLOODDBZQ
convox env set
Set an environment variable for an application. This command updates an environment variable or creates a new one, generating a new release in the process. This release must be promoted to apply the changes.
$ convox env set FOO=BAR -a nodejs -r demo-rack
Setting FOO... OK
Release: RXYHIAAHXOZ
convox env edit
This command launches an interactive editor allowing you to modify environment variables directly. Changes made through the editor will generate a new release that must be promoted to take effect.
$ convox env edit -a nodejs -r demo-rack
# Opens an interactive editor for environment variables.
convox releases
List releases of an application. This command displays a detailed list of all releases associated with a specified application, showing each release's ID, status, associated build, creation time, and description.
$ convox releases -a nodejs -r demo-rack
ID STATUS BUILD CREATED DESCRIPTION
RXYHIAAHXOZ BDBCKOFVPCR 15 seconds from now env add:FOO
RVTLOODDBZQ active BDBCKOFVPCR 3 minutes ago build 01cddb4eb3
convox releases promote
Promote a specific release. This command allows you to set a specified release as the active one for an application.
$ convox releases promote RXYHIAAHXOZ -a nodejs -r demo-rack
Promoting RXYHIAAHXOZ...
2024-05-01T03:48:13Z system/k8s/atom/app Status: Running => Pending
2024-05-01T03:48:15Z system/k8s/web Scaled up replica set web-546648449c to 1
...
2024-05-01T03:49:31Z system/k8s/atom/app Status: Updating => Running
OK
Service Management and Scaling
Commands focused on managing services and scaling applications.
convox services
List services associated with an application. This command provides a detailed view of all services that are part of a specified application, including each service's name, domain, and port mappings.
$ convox services -a nodejs -r demo-rack
SERVICE DOMAIN PORTS
web web.nodejs.3f031abdcc84be6b.convox.cloud 443:3001
convox exec
Execute a command in a running container. This command allows you to interact directly with a specific service container within an application, executing commands as if you were inside the container. For example, you can drop into the shell of a service by running convox exec serviceName sh.
$ convox exec web sh -a nodejs -r demo-rack
/usr/src/app # ls
Dockerfile README.md app.js convox.yml
convox ps
List processes running for an application. This command provides an overview of all active processes associated with a specified application, displaying details such as process ID, service type, current status, release ID, and the time each process started.
$ convox ps -a nodejs -r demo-rack
ID SERVICE STATUS RELEASE STARTED COMMAND
web-855d47f8f7-5hk79 web running RVTLOODDBZQ 1 minute ago
convox ps info
Get detailed information about a specific process. This command provides comprehensive details on an individual process running within an application, including the process ID, application name, command executed, instance details, associated release, service type, start time, and current status.
$ convox ps info web-546648449c-f4k2n -a nodejs -r demo-rack
Id web-546648449c-f4k2n
App nodejs
Command
Instance ip-10-1-96-207.ec2.internal
Release RXYHIAAHXOZ
Service web
Started 4 minutes ago
Status running
convox scale
View and adjust the scaling settings for services within an application. This command displays the current scaling configurations for each service associated with an application, including desired and actual running instances, as well as allocated CPU and memory resources. You can also use this command to modify these settings to scale your services up or down based on your operational needs.
convox scale - View the current scaling settings for all services within an application.
$ convox scale -a nodejs -r demo-rack
SERVICE DESIRED RUNNING CPU MEMORY
web 1 1 256 512
convox scale serviceName
Specifically scale a service within an application. This command allows you to finely adjust the scaling settings for a specific service, such as the number of instances (--count), the amount of CPU (--cpu), and memory resources (--memory) allocated. Use this command to optimize resource usage and handle varying loads manually.
$ convox scale web --count 3 -a nodejs -r demo-rack
Scaling web...
OK
$ kubectl get pods -n demo-rack-nodejs
NAME READY STATUS RESTARTS AGE
web-546648449c-6vljv 0/1 Pending 0 24s
web-546648449c-dvlp7 0/1 Pending 0 24s
web-546648449c-jbsr4 1/1 Running 0 13m
Advanced Operations and Troubleshooting
Commands that involve more advanced operations like key management, SSH access, running detached processes, and monitoring.
convox certs
List SSL certificates managed by Convox for your applications. This command displays all SSL certificates currently registered with Convox, showing each certificate's ID, the domain it is associated with, and its expiration date.
$ convox certs -r demo-rack
ID DOMAIN EXPIRES
api-certificate api.3f031abdcc84be6b.convox.cloud 2 months from now
cert-web web.nodejs.3f031abdcc84be6b.convox.cloud 2 months from now
convox instances
List all instances in the current rack along with their metrics. This command provides a detailed view of each instance operating within your rack, including information such as instance ID, status, uptime, number of processes running (PS), CPU usage, memory utilization, and network addresses.
$ convox instances -r demo-rack
ID STATUS STARTED PS CPU MEM PUBLIC PRIVATE
ip-10-1-122-207.ec2.internal running 5 minutes ago 9 2.80% 52.00% 10.1.122.207
ip-10-1-145-130.ec2.internal running 5 minutes ago 11 3.16% 54.26% 10.1.145.130
ip-10-1-214-115.ec2.internal running 5 minutes ago 11 2.80% 55.23% 10.1.214.115
convox instances keyroll
Add SSH keys for instances in the rack. This command generates a new SSH key pair and applies it to the instances within the specified rack. If you do not pipe the output, the new private key will be displayed in your terminal. To securely save the key to a file without displaying it in the terminal, use the pipe command shown below to filter and redirect the output to a file named mykey.pem - or any other file name you choose.
$ convox instances keyroll -r demo-rack | grep -A 100 'BEGIN RSA PRIVATE KEY' > mykey.pem
convox instances ssh
SSH into a specific instance using a newly rotated key. After generating and saving your new SSH key with convox instances keyroll, use the key to establish a secure SSH connection to an instance. Specify the instance and key file as shown in the command below. This allows you to directly interact with the instance for troubleshooting and management purposes.
$ convox instances ssh ip-10-1-145-130.ec2.internal --key mykey.pem -r demo-rack
Last login: Wed Apr 24 04:40:21 2024 from 54.240.230.242
...
[ec2-user@ip-10-1-145-130 ~]$ exit
logout
convox run
Execute a command in a new process within a service container. This command runs a specified command as a new process in a service container. You can run the command in detached mode using the -d option, which allows the command to operate in the background and frees up the terminal. Additionally, you can specify an entrypoint with -e and set a timeout for the command with -t timeout. This functionality is useful for various operations including administrative tasks, temporary modifications, or maintenance commands.
$ convox run web sleep 500 -d -a nodejs -r demo-rack
Running detached process... OK, web-kpklb
convox logs
View logs for an application. This command streams real-time logs from all components of the specified application, allowing you to monitor ongoing activities and troubleshoot issues as they occur.
$ convox logs -a nodejs -r demo-rack
2024-05-01T03:55:22Z service/web/web-546648449c-f4k2n PING
2024-05-01T03:55:27Z service/web/web-546648449c-f4k2n PING
2024-05-01T03:55:32Z service/web/web-546648449c-f4k2n PING
2024-05-01T03:55:37Z service/web/web-546648449c-f4k2n PING
Conclusion
As you have explored in this guide, mastering the use of Convox commands can significantly enhance your ability to manage and optimize your applications and racks effectively. By familiarizing yourself with the command options and contexts explained throughout this documentation, you are now equipped to navigate the Convox environment with confidence. Remember, the key to effective command usage is understanding when and where to apply them, and always ensuring that your commands are targeting the intended scope. For further details on each command, don't hesitate to use the --help option for on-the-fly assistance. Thank you for following this guide, and we hope it serves you well in managing your Convox deployments seamlessly.
