-
Notifications
You must be signed in to change notification settings - Fork 4
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
6 changed files
with
148 additions
and
292 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,54 +1,75 @@ | ||
| # Shipped - Install CLI | ||
| # Shipped - CLI | ||
|
|
||
| The Shipped CLI provides command line access to Shipped services, including most API and UI functions. In addition, Shipped provides commands for controlling your local environment, such as bootstrap, build, and test. | ||
|
|
||
| You must have a GitHub account to sign in to Shipped. | ||
|
|
||
| ## Sign up with GitHub | ||
|
|
||
| 1. Log in to <a href="https://ciscoshipped.io">Shipped UI</a>. | ||
|
|
||
| 1. Click **Sign up with GitHub**. | ||
|
|
||
| 1. Click **Authorize application** to allow Shipped to read your public data. You only need to do this the first time you use Shipped. | ||
|
|
||
|  | ||
|
|
||
| 1. Click your user name and select **My Profile** from the drop-down list. | ||
|
|
||
|  | ||
|
|
||
| ## Supported OS | ||
| 1. Click **Show My User Token**. | ||
|
|
||
|  | ||
| 1. Copy this token. | ||
|
|
||
| ## Install Shipped CLI | ||
|
|
||
| Shipped CLI supports the following OS: | ||
|
|
||
| - MacOS | ||
| - Windows (7 or later) | ||
| - Linux (Ubuntu 13 or later) | ||
| - <a href="Linux">Linux </a>(Ubuntu 13 or later) | ||
| - <a href="MacOs">MacOS </a> | ||
| - <a href="Windows">Windows </a> (7 or later) | ||
|
|
||
| <a name="installation"></a> | ||
| ## Installation | ||
| Shipped installation requires root or Administrator privileges. | ||
|
|
||
| <a name="Linux"></a> | ||
| ### Linux | ||
| Copy the following command, paste it into a terminal window, and run it. | ||
|
|
||
| curl -kL https://bintray.com/artifact/download/shippedrepos/shipped-install/linux/shipped-setup.sh | bash -s | ||
|
|
||
| <a name="MacOS"></a> | ||
| ### MacOS | ||
| Copy the following command, paste it into a terminal window, and run it. | ||
|
|
||
| curl -kL https://bintray.com/artifact/download/shippedrepos/shipped-install/mac/shipped-setup.sh | bash -s | ||
|
|
||
| <a name="Windows"></a> | ||
| ### Windows | ||
|
|
||
|
|
||
|
|
||
| 1. Download shipped-install.exe and save it on your desktop. | ||
|
|
||
| https://bintray.com/artifact/download/shippedrepos/shipped-install/windows/shipped-install.exe | ||
|
|
||
| 1. Double-click *shipped-install.exe*, click **Run**. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| It takes several minutes to complete the installation. | ||
|
|
||
|  | ||
|  | ||
|
|
||
| 1. Press **Enter** to exit the installation. | ||
|
|
||
| 1. Open a command window, and type the following command to verify that the installation is successful. | ||
| ## Verify | ||
| Open a command window, and type the following command to verify that the installation is successful. | ||
|
|
||
| shipped -v | ||
| shipped -v | ||
|
|
||
| The Shipped version is displayed. | ||
| The Shipped version is displayed. | ||
|
|
||
| Cisco Shipped 1.0 b0 20160609 014325 | ||
|
|
||
| Cisco Shipped 1.0 b0 20160609 014325 | ||
|
|
||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,119 +1,52 @@ | ||
| # Shipped - Create an Application | ||
|
|
||
| To use the Shipped CLI to create an application, you need to: | ||
|
|
||
| - Sign up with GitHub | ||
| - Authorize Shipped to create a GitHub repository on your behalf | ||
| - Obtain an API token to identify yourself to Shipped | ||
|
|
||
| ## Sign up with GitHub | ||
|
|
||
| 1. In a browser, go to [http://ciscoshipped.io/](http://ciscoshipped.io/). | ||
|
|
||
| 1. Click **Sign up with GitHub**. | ||
|
|
||
| The GitHub site opens in your browser. | ||
|
|
||
| ## Provide Authorization to Shipped | ||
|
|
||
| 1. Click **Authorize application** to allow Shipped to read your public data. You only need to do this the first time you use Shipped. | ||
|
|
||
|  | ||
|
|
||
| The Shipped UI opens. | ||
|
|
||
| ## Obtain an API Token | ||
|
|
||
| 1. Click your user name and select **My Profile** from the drop-down list. | ||
|
|
||
|  | ||
|
|
||
| 1. Click **Show My User Token**. | ||
|
|
||
|  | ||
|
|
||
| 1. Copy this token. | ||
| # Shipped - Create Application and Service | ||
|
|
||
| ## Access CLI | ||
|
|
||
| 1. Open a command window. | ||
|
|
||
| 1. Enter shipped **help -t xxx**, where xxx is the API token you copied earlier. | ||
| 1. Enter shipped **help -t xxx**, where xxx is the token you copied earlier. | ||
|
|
||
| Shipped displays an overview help information. | ||
|
|
||
| **Note**: Shipped stores your API token. You do not need to provide this token again. | ||
|
|
||
| You are now ready to use the Shipped CLI. | ||
|
|
||
| <a name="Overview"></a> | ||
| ## CLI Command and Help Overview | ||
|
|
||
| Shipped CLI commands typically take the form: | ||
|
|
||
| shipped command subcommand arguments | ||
|
|
||
| where command is the Shipped object you want to work with (such as "application" or "service"), subcommand is what you want to do with it (such as "create" or "list"), and arguments vary depending on the command and subcommand. You can abbreviate command, subcommand, and arguments by truncation to the minimum length necessary for non-ambiguity. | ||
|
|
||
| To obtain help for a command or subcommand, either use the help command or include a `-h` or `--help` argument anywhere in the command. For example, to obtain help for the `project create` command, type any of the following: | ||
|
|
||
| shipped help project create | ||
| shipped project create -h | ||
| shipped proj cr --help | ||
|
|
||
| The last example also is an example of abbreviating a commands and subcommand. | ||
|
|
||
| Additional CLI documentation is available online at [https://developer.cisco.com/site/shipped/documents/cli-guide/](https://developer.cisco.com/site/shipped/documents/cli-guide/). | ||
|
|
||
| <a name="create"></a> | ||
| ## Create a Application | ||
| Shipped groups services into projects. You can create a project by providing its name and and an optional description: | ||
| ## Create an Application | ||
| Shipped groups services into applications. You create an application with the <code>project create</code> command, and provide a name and optional description for the application. | ||
|
|
||
| Example: | ||
|
|
||
| shipped project create name=Demo desc="A Demo Application" | ||
| shipped project create name=testProject desc="A Demo Application" | ||
|
|
||
| Shipped shows successful completion by echoing the project name and description. | ||
| Shipped echoes the project name and description. | ||
|
|
||
| Changed to new project directory c:\shipped\Demo | ||
| Application Description | ||
| ------- ----------- | ||
| Demo A Demo Application | ||
|
|
||
|
|
||
| ------- ----------- | ||
| testProject A Demo Application | ||
|
|
||
| <a name="service"></a> | ||
| ## Create a Service | ||
|
|
||
| A service is an independently deployable component of a project. Most services are based on a buildpack that includes starter code for the service. You can list buildpacks with the command: | ||
|
|
||
| shipped buildpack list | ||
| 1. Issue the <code>buildpack getall</code> command to see a list of available buildpacks. | ||
|
|
||
| Example: | ||
|
|
||
| shipped buildpack | ||
|
|
||
| Shipped shows the available buildpacks. | ||
|
|
||
| Shipped shows the available buildpacks: | ||
|  | ||
|
|
||
| BuildPack | ||
| --------- | ||
| golang | ||
| Cisco Tropo WebAPI | ||
| CiscoCMX API | ||
| Cisco APICEM | ||
| ExpressJS | ||
| Java Spring Boot | ||
| Python | ||
| Cisco Spark | ||
| Dropwizard | ||
| Grunt.JS | ||
| Ruby on Rails | ||
| PHP | ||
| 1. Issue the <code>service create</code> command, and provide the name of the project, the name of the buildpack to use, and the name for the new service. | ||
|
|
||
| Example: | ||
|
|
||
| To create a service, provide the name of the project you just created, the name of the buildpack you want to use, and the name of the new service. For example, to create a service using the Go language, use the command: | ||
| shipped service create testProject golang name=testservice | ||
| Respond: | ||
|
|
||
| shipped services create demo golang name="goservice" | ||
|  | ||
|
|
||
| Once again, Shipped shows successful completion by echoing service information. | ||
|
|
||
| Service BuildPack Application | ||
| ------- --------- ------- | ||
| goservice golang Demo | ||
|
|
||
| When you create a service, Shipped automatically creates a GitHub repository for its source code and sets up a CI build so that any push you make to the repository automatically causes a build. We'll see how to use these in subsequent sections. | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,75 +1,45 @@ | ||
| # Shipped - Local Bootstrap | ||
|
|
||
| One of the most important features of Shipped is the ability to import a project and its services to your local developer machine. On your local machine, you can review and modify a service's source code, including committing it to a GitHub repository. In addition, you can build and test a service in a VM that Shipped can create for you on local machine. The CLI `local` command includes a number of subcommands for working with locally deployed projects and services. To see a list of them, enter the command: | ||
|
|
||
| shipped help local | ||
| One of the most important features of Shipped is the ability to import a project and its services to your local machine. Bootstrapping a project creates a local Git repository for each of its services that is linked to the remote GitHub repository that Shipped created when you created the service. The local repository is in a directory on your local machine and the remote repository is in the cloud. | ||
|
|
||
| 1. Change to the directory where you want to place the project and service. | ||
|
|
||
| ## Local Bootstrap | ||
| You use the `local bootstrap` command to import a project and its services and set up a local VM. To do this, change to the directory where you want to place the project and services and issue the command: | ||
|
|
||
| shipped local bootstrap demo | ||
|
|
||
| In this case, **demo** is the name of the project you created in the <a href="2.md">previous section</a>. | ||
|
|
||
| Bootstrap may take a few minutes, with the time depending on the number of services and the buildpacks they use. Shipped provides detailed output of the progress of bootstrap: | ||
|
|
||
| git 2.7.2 is already installed. | ||
| ============================================================ | ||
| Check prerequisite software | ||
| ============================================================ | ||
| docker 1.10.1 is already installed. | ||
| docker-compose 1.6.0 is already installed | ||
| docker-machine 0.6.0 is already installed | ||
| virtualbox 5.0.14r105127 is already installed | ||
| Verifying docker installation | ||
| ============================================================ | ||
| Cloning Repositories | ||
| ============================================================ | ||
| Cloning service 1 goservice (0770b248-f121-11e5-bd40-0242ac110116) into c:\Users\David\shipped\Demo\goservice | ||
| . . . | ||
| ============================================================ | ||
| Bootstrap Sandbox VM | ||
| ============================================================ | ||
| Assigned port localhost:38891 to service goservice | ||
| Building goservice | ||
| . . . | ||
| Creating demo_goservice_1 | ||
| Project Demo bootstrap complete | ||
| ============================================================ | ||
| 1 service is running and is available at the web address below | ||
| ------------ ------------ -------------- ------ ------------------- | ||
| Service Name Container ID Container Name Status Service Web Address | ||
| ------------ ------------ -------------- ------ ------------------- | ||
| goservice 12d6c99ddfe4 demo_goservice_1 Up 3 seconds http://localhost:38891 | ||
| ============================================================ | ||
| Bootstrap is complete and Shipped has set up a CI build for each of your services. | ||
| To initiate a build for a service, do a git commit and push for that service. | ||
|
|
||
| <a name="verify"></a> | ||
| 1. Issue the <code>local bootstrap</code> command, and provide the name of the project to be bootstrapped. You can add the <code>--fast</code> flag to speed up the bootstrap process by skipping VM and container deployment. | ||
|
|
||
| shipped lcl bootstrap TestProject --fast | ||
| **Note**: You can abbreviate any commands by truncating them to the minimum length necessary for unambiguous specification. | ||
|
|
||
| Shipped provides detailed output of the bootstrap progress: | ||
|
|
||
|  | ||
|
|
||
| ## Verify | ||
| The last few lines of bootstrap output show the status of services deployed in the local VM. The output above shows that Shipped successfully deployed service `goservice` to the local VM and that it has a web service available at the URL http://localhost:38891 (even though the service is running in a VM, its web services are exposed through a port on your local machine). To verify the service is running, copy and paste the URL from the service status report into a browser window and press Enter. The browser shows the service's output: | ||
| Copy and paste **http://localhost:38891** (the assigned port) into a browser window and press **Enter**. The browser shows the output: | ||
|
|
||
|  | ||
|
|
||
| ## Service Logs and Status | ||
| Most services write logs while they are running. You can review a service's logs with the `local logs` command: | ||
|
|
||
| shipped local logs Demo goservice | ||
| ## View Service Logs | ||
|
|
||
| Most services write logs while they are running. Issue the **local logs** command, and provide the names of the project and service to be viewed. | ||
|
|
||
| Example: | ||
|
|
||
| shipped lcl logs testproject testservice | ||
|
|
||
| Respond: | ||
|
|
||
|  | ||
|
|
||
|
|
||
| Shipped responds: | ||
| ## View Service Status | ||
| Issue the <code>local status</code> command, and provide the names of the project and service to be viewed. | ||
|
|
||
| Logs for service goservice: | ||
| Example app listening at http://localhost:8888 | ||
| OK | ||
| shipped lcl status testproject testservice | ||
|
|
||
| The port shown in the sample log is that used within the VM running the service, which is all that the service knows about. This port is mapped to a different port in your development machine, which is the one shown in the status report displayed at the end of bootstrap. You can retrieve this report at any time with the `local status` command: | ||
| Respond: | ||
|
|
||
| shipped local status | ||
|  | ||
|
|
||
| Shipped responds with the same information it shows at the end of bootstrap: | ||
|
|
||
| 1 service is running and is available at the web address below | ||
| ------------ ------------ -------------- ------ ------------------- | ||
| Service Name Container ID Container Name Status Service Web Address | ||
| ------------ ------------ -------------- ------ ------------------- | ||
| goservice 5fd7068061c6 demo_goservice_1 Up 28 minutes http://localhost:38891 |
Oops, something went wrong.