The Terminal Ranger’s creed: Why use mice when keyboards suffice? Sometimes even an elegant interface isn’t your cup of tea. Well lucky for you, we have written a rock solid command line application that lets you create, deploy, rollback, securely connect to your live database, etc... After reading this guide, you should be able to:
- Install the Pagoda Terminal Client
- Manage your Pagoda Box apps from your command line
- Enjoy the awesomeness of a streamlined app management workflow
Installing the Terminal Client
The Pagoda Box Terminal Client is a rubygem so installation is pretty simple. First off, you need to have Ruby installed. Installation is different for each operating system.
Ruby and RubyGems come pre-installed on Mac OSX. As long as you are running v10.5 or later, you should be good to go.
There are a couple of different ways to install Ruby in Windows. We have found the easiest way is to use this auto-installer. If this doesn’t work for you, a google search will give you a pretty good list of installation walk-throughs.
Just use your preferred package manager to download the Ruby package. For Ubuntu users, the gem is available through getdeb.net
Once Ruby is installed, simply run the following command to install the Pagoda RubyGem:
TerminalInstall the Pagoda Gem
Using the Terminal Client
The majority of the information covered in the following section can quickly be referenced using the “pagoda help” command.
The first time you use the Pagoda Terminal Client, you will be asked for a username and password. Use your Pagoda Box username and password. You will only have to do this once. Once you are logged in, you are ready to go.
Just as with other command line clients, all commands specific to the Pagoda terminal client must be prefaced by “pagoda”.
|clone||Clones an application from Pagoda Box|
|create||Creates a new application on Pagoda Box|
|deploy||Deploys your code to your live Pagoda Box app|
|destroy||Removes your application|
|help||Shows lists of possible commands associated to a particular command|
|info||Shows information about your app|
|init||Connects your local repo with your Pagoda Box repo|
|initconfig||Initializes the config file using current global options. If you need to change the Pagoda Box username and password associated with your gem, you can do it here.|
|key:gen||Generates an ssh key and posts it to Pagoda Box|
|key:push||Posts an existing ssh key to Pagoda Box|
|list||Lists your apps on Pagoda Box|
|log||Outputs an aggregated stream of application logs|
|rename||Renames your application|
|rollback||Rolls your app back to the previously deployed commit|
|tunnel||Tunnels to a component in your application|
-a <name> | --app=<name>
Set the application name (Only necessary when not in repo dir).
-u <username> | --username=<username>
When set, will not attempt to save your username. Also over-rides any saved username.
-p <password> | --password=<password>
When set, will not attempt to save your password. Also over-rides any saved password.
Executes all commands without confirmation request.
Deploying - pagoda deploy :
-b <branch> | --branch=<branch>
Specify the branch name. By default uses the branch your local repo is on.
-c <commit> | --commit=<commit>
Specify the commit id. By default uses the commit HEAD is set to.
Tunneling - pagoda tunnel :
-c <component_name> | --component=<component_name>
Specify the component you want to tunnel to.
Logs - pagoda log :
-c <number> | --count=<number>
Sets the number of log entries returned.
-l | --live
Outputs a live stream or your aggregated application logs.
Launching an App
To launch an app, you must be inside the root directory of your repo. Use the following command:
TerminalLaunch an App
This will automatically create a repo on Pagoda Box and attach a "pagoda" remote. Your Pagoda Box repo is then pushed live. If you already have a remote named "pagoda," it will allow you to name your new remote.
Cloning an App from Pagoda Box
To clone an app from a Pagoda Box, you must be an owner or collaborator of that app. Simply use the following command:
TerminalCloning an App from Pagoda Box
To deploy the current state of your local instance while inside your repo:
TerminalDeploy While Inside Your Repo
If you’re outside of your repo, just specify which repo you would like to deploy:
TerminalDeploy While Outside Your Repo
You are also able to specify which branch to deploy:
TerminalSpecify a Branch to Deploy
Or even specify a commit:
TerminalSpecify a Commit to Deploy
The ability to quickly rollback code is a nice tool for any developer to have in their tool-belt. Using the rollback command will roll your app back to the previously deployed commit. If you’re inside your repo, use the following command:
TerminalRollback While Inside Repo
If you’re outside of your repo, you simply need to specify which app you would like to roll back:
TerminalRollback While Outside Repo
Connecting Your Local Repo to an Existing App
While inside your repo, run the following command to connect to an existing app on Pagodabox.
TerminalConnecting Your Local Repo to an Existing App
This automatically creates a "pagoda" remote associated to the git clone address with the specified app. If your repo already has a "pagoda" remote, you will be able to name the new remote.
Destroying an App
Destroying an app is really simple. If you’re inside your repo, just use the following command:
TerminalDestroy an App While Inside Repo
You will be asked to confirm whether or not you really want to destroy your app. If you want to skip the confirmation, just append the “-f” parameter to the previous command. This will force the command without any confirmation.
If you are not inside your app’s repo, you can still destroy it but you need to specify the app you would like to destroy:
TerminalDestroy an App While Outside Repo
Managing SSH Keys
For some transactions, we need your public SSH Key. There's a couple of ways you can get it to us.
TerminalPosting Your Existing SSH Key to Pagoda Box
You can also generate a new public SSH key and push it to Pagoda Box by using the following command:
TerminalGenerating a New SSH Key and Posting it to Pagoda Box
Creating a Database Tunnel
This functionality is so awesome we decided to give it its own guide. Check out the Creating a Secure Database Tunnel from Your Desktop Guide.
Viewing Application Logs
This functionality is covered in the Log Management guide.
Pagoda in Your Workflow
The goal of the Pagoda Terminal Client is to make your code deployment workflow as frictionless as possible. You can still deploy new apps and commits, rollback, or scale your app using the Pagoda Box Admin Panel, but that can break up your workflow. Using the terminal client, you can do all these things in the same place you’re managing your git repo, so you’re workflow is as uninterrupted as possible.
Here’s an example:
TerminalExample: Pagoda Terminal Workflow
In this example, a new app was created, launched, code was changed, added, committed,and deployed to the live instance on Pagoda Box, rolled back, and destroyed all from a command line, in under 2 minutes.
Table of Contents
- Launching an App
- Launch an App
- Cloning an App from Pagoda Box
- Cloning and App from Pagoda Box
- Deploying Commits
- Deploy While Inside Your Repo
- Deploy While Outside Your Repo
- Deploy Most Recent Commit in Github Repo
- Specify a Branch to Deploy
- Specify a Commit to Deploy
- Rolling Back
- Rollback While Inside Repo
- Rollback While Outside Repo
- Connecting Your Local Repo to an Existing App
- Connecting Your Local Repo to an Existing App
- Destroying an App
- Destroy an App While Inside Repo
- Destroy an App While Outside Repo
- Managing SSH Keys
- Posting Your Existing SSH Key to Pagoda Box
- Generating a New SSH Key and Posting it to Pagoda Box
- Creating a Database Tunnel
- Viewing Application Logs