NAV

Shipped Reference

Shipped is an integrated development, deployment and operations solution – a centralized location for developers to manage various aspects of an application.

Developers can authenticate with Github, assemble an application with various services and dependencies, and deploy it all to any public or on-premise cloud. Operations teams can then monitor and receive alerts from running applications.

Concepts

Containers

Containers are consistent, buildable and deployable information holders. They make standardized development and deployment easy, providing efficient operations.

Shipped uses Docker, a popular container format, for builds and deployments. Some understanding of how to use Docker for development might be helpful as you integrate with Shipped. Once your Docker container works, you can automatically build and deploy your code.

Learn more about Docker and containers at Docker.com

Containerizing your app

Crafting the right container to run your application in depends a great deal on the specifics of your application.

You must:
1. Choose a base image
2. Install dependencies
3. Add build commands
4. Tell Docker how to run the app

An example Ruby on Rails Dockerfile

FROM ruby:2.2.0
RUN apt-get update -qq && apt-get install -y build-essential libpq-dev
RUN mkdir /myapp
WORKDIR /myapp
ADD Gemfile /myapp/Gemfile
ADD Gemfile.lock /myapp/Gemfile.lock
RUN bundle install
ADD . /myapp
CMD rails s

Docker provides some really good guides for some application frameworks that should give you an idea of how to construct your Dockerfile. They have examples for Wordpress, Rails, and Django. And here’s a good blog post that outlines a static compilation use case in Golang

Local Bootstrap

Firstly, note that you do not need to have a local bootstrap to develop applications using Shipped. Once a repository is hooked up, you can develop as you always have and not worry about this at all. For users with many services who may not want to deal with the hassle of setting them all up individually on your local system, this feature was made for you.

Since all of our applications are containerized, we can easily provision a locally running environment using docker-compose. That allows you to focus on developing the specific services you care about. In order to develop locally, you should have a firm understanding of docker and how containers are built, that way you’ll know when/if they need to be restarted to show your changes. We mount the service containers with your local code directories right there in the container. Local development goes faster if you have a built-in code reloading mechanism, which you get for free with frameworks like Rails in Ruby or Re-run in Golang that will propagate local filesystem changes into the container without having to rebuild it. If you don’t have some kind of dynamic code reloading, you may need to rebuild your containers for them to show your changes.

We suggest finding a article outlining the development workflow for using docker with your frameworks of choice, like this one for Ruby on Rails

Health Checks

A health check path in Shipped is an application endpoint that will return a 2XX http response code if the service is functioning properly. If a healthcheck is set, a successful response code will put the service into the load balancer rotation and a failed code will remove it from rotation.

Health checks for non-http services are not supported at this time.

Underlying Tools

A complete understanding of the tools used by Shipped is unnecessary to get value out of it, but understanding the internals will be helpful for advanced users.

Vagrant

Vagrant is a portable development environment solution that Shipped uses to create a standardized development environment for each of your developers. Every service that your application needs will run in a Docker container within the same local virtual machine, so new developers receive a fully functional environment with zero configuration. You shouldn’t need to change this, but if you need it, the Vagrantfile provided by the Shipped bootstrap process is within the hidden .shipped directory in the root of your project. If new services are added by other developers, you may need to re-run the bootstrap script to get the updated local development environment.

Learn more

Docker

Docker is a containerization solution. It allows you to create completely isolated, repeatable, deployable artifacts. Shipped uses it to run each of your services in isolation. Each service you add to your project has a corresponding Dockerfile that’s exposed for you. Shipped buildpacks favor a small footprint with limited functionality, but you should feel free to modify this file to fit your needs. If your service has many dependencies, it may make sense to build some of them into your image to decrease build times, for example.

Learn more

Drone

Drone is a continuous integration solution. Shipped adds a web hook into your services’ repositories; this web hook triggers a build in Drone each time a new commit is made on any branch. Build results show up in Shipped and successful builds will show up on the [Deploy] page and be ready to release to an Environment. Logs from failed builds are also available from the UI.

The Shipped-CLI bootstrap provides a default .drone.yml file for each [service]. To change how a service is built within Drone, you can edit and commit the .drone.yml file within that service’s directory.

Learn more

API Reference

Authentication

There are two ways to authenticate with Shipped.

Api Tokens

Each user has a secret api_token attribute. Find this token on the settings page. Passing this value as a querying parameter will authenticate that user.

curl https://api.ciscoshipped.io/users/current

Example Response

{
  "auth_token": "",
  "id":123456,
  "login":"adama",
  "avatar_url":"https://avatars.githubusercontent.com/u/123456?v=3",
   "html_url":"https://github.com/ikinsey",
  "name":"Bill Adama",
  "email":"wadama@galactica.net",
  "api_token": "XVlBwuiEEIkakjwoifslkw"
}

This endpoint authenticates the user associated with the token, and retuns that user.

HTTP Request

GET https://api.ciscoshipped.io/users/current?api_token=<TOKEN>

URL Parameters

Parameter Description
api_token The api token found in settings.

Once you’ve logged in with oauth on https://ciscoshipped.io, you receive an encrypted, signed cookie that can be used for API authentication.

Projects

A project is the largest scope within Shipped. It’s is a collection of services and dependencies that comprise a functional, deployable application.

You can invite users to collaborate with you on your project, integrate with other services using webhooks and more from your project’s settings page.

Get all projects

curl https://api.ciscoshipped.io/projects

Example Response

[
   {
      "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "name":"php-hello-world",
      "event_count": 4,
      "user_count": 1,
      "last_good_release": "b475996d-dd1e-11e4-9917-0090f5d8986c",
   },
   {...},
   {...}
]

Retrieves a list of all publicly visible projects.

HTTP Request

GET https://api.ciscoshipped.io/projects

Get your projects

curl https://api.ciscoshipped.io/projects

Example Response

[
   {
      "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "name":"php-hello-world",
      "event_count": 4,
      "user_count": 1,
      "last_good_release": "b475996d-dd1e-11e4-9917-0090f5d8986c",
   },
   {...},
   {...}
]

Gets all projects for the currently authenticated user. This is determined by the cookie set on login.

HTTP Request

GET https://api.ciscoshipped.io/projects

Get a project

curl https://api.ciscoshipped.io/projects/b475996d-dd1e-11e4-9917-0090f5d8986c

Example Response

{
  "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
  "name":"php-hello-world",
  "event_count": 4,
  "user_count": 1,
  "last_good_release": "b475996d-dd1e-11e4-9917-0090f5d8986c",
}

Retrieves a project.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Create a project

curl https://api.ciscoshipped.io/projects -H 'Content-type: application/json' -d '{'"name":"php-hello-world"}'

Example Response

{
  "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
  "name":"php-hello-world",
  "event_count": 0,
  "user_count": 1,
}

Creates a project and returns the created project.

HTTP Request

POST https://api.ciscoshipped.io/projects

Query Parameters

Parameter Default Description
name - The name of the project

Update a project

curl https://api.ciscoshipped.io/projects/b475996d-dd1e-11e4-9917-0090f5d8986c -H 'Content-type: application/json' -d '{'"name":"php-hello-world2"}'

Example Response

{
  "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
  "name":"php-hello-world2",
  "event_count": 0,
  "user_count": 1,
}

Updates a project, and returns the updated project.

HTTP Request

PUT https://api.ciscoshipped.io/projects/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Query Parameters

Parameter Default Description
name - The name of the project

Delete a project

curl https://api.ciscoshipped.io/projects/b475996d-dd1e-11e4-9917-0090f5d8986c -X DELETE

Deletes a project.

HTTP Request

DELETE https://api.ciscoshipped.io/projects/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Services

Services are github repositories that are part of a project.

List all services

Retrieves the services for a project

curl 'https://api.ciscoshipped.io/projects/19d87036-532a-11e5-913f-0242ac1100c4/services'

Example Response

[
   {
     "type": "ServiceRepo",
     "project_id": "19d87036-532a-11e5-913f-0242ac1100c4",
     "id": "2355356f-532a-11e5-9140-0242ac1100c4",
     "buildpack_id": "f5e20759-f2b9-11e4-963b-14109fd75217",
     "name": "phptest242",
     "image_source": "https://api.ciscoshipped.io/cli/static/images/php.svg",
     "build_image": "bradrydzewski/php:5.5",
     "deploy_image": "npateriyainsecure/php-hello-world",
     "repository": "https://github.com/mikejihbe/phptest242",
     "organization": "",
     "default_cpu": 1,
     "default_ram": 512,
     "build_command": "",
     "run_command": "",
     "test_command": "echo noop",
     "container_port": 80,
     "container_shared_directory": "/app",
     "bootstrap_template_repo": "http://github.com/CiscoCloud/shipped-php-template",
     "github_repo_id": 41928815,
     "drone_repo_enabled": true,
     "health_check_path": "/"
   },
   {...},
   {...}
]

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/services

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to list services

Get a service

Retrieves a project service

curl 'https://api.ciscoshipped.io/projects/19d87036-532a-11e5-913f-0242ac1100c4/services/2355356f-532a-11e5-9140-0242ac1100c4'

Example Response

{
     "type": "ServiceRepo",
     "project_id": "19d87036-532a-11e5-913f-0242ac1100c4",
     "id": "2355356f-532a-11e5-9140-0242ac1100c4",
     "buildpack_id": "f5e20759-f2b9-11e4-963b-14109fd75217",
     "name": "phptest242",
     "image_source": "https://api.ciscoshipped.io/cli/static/images/php.svg",
     "build_image": "bradrydzewski/php:5.5",
     "deploy_image": "npateriyainsecure/php-hello-world",
     "repository": "https://github.com/mikejihbe/phptest242",
     "organization": "",
     "default_cpu": 1,
     "default_ram": 512,
     "build_command": "",
     "run_command": "",
     "test_command": "echo noop",
     "container_port": 80,
     "container_shared_directory": "/app",
     "bootstrap_template_repo": "http://github.com/CiscoCloud/shipped-php-template",
     "github_repo_id": 41928815,
     "drone_repo_enabled": true,
     "health_check_path": "/"
   }

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>

URL Parameters

Parameter Description
PROJECT_ID The project id for the service
SERVICE_ID The service id to retrieve

Create a service

Creates a service for a project, and returns the created service.

curl 'https://api.ciscoshipped.io/projects/19d87036-532a-11e5-913f-0242ac1100c4/services' -d '{"type": "ServiceRepo", "project_id":"34a35726-66e9-11e5-99df-0242ac110120","buildpack_id":"4e0c194a-1c66-11e5-bb2c-a45e60e7c003","name":"rails","public":true,"organization":""}'

Example Response

{
"type": "ServiceRepo",
"project_id":"34a35726-66e9-11e5-99df-0242ac110120",
"id":"4455979b-66e9-11e5-99e0-0242ac110120",
"buildpack_id":"4e0c194a-1c66-11e5-bb2c-a45e60e7c003",
"name":"rails",
"image_source":"https://api.ciscoshipped.io/cli/static/images/ruby-on-rails-alt.svg",
"build_image":"bradgearon/ruby:2.2.2",
"deploy_image":"bradgearon/ruby:2.2.2",
"repository":"https://github.com/mikejihbe/railssss",
"organization":"",
"public":true,
"default_cpu":1,
"default_ram":512,
"build_command":"/app/bin/build",
"run_command":"/app/bin/run",
"test_command":"/app/bin/test",
"container_port":3000,
"container_shared_directory":"/app",
"bootstrap_template_repo":"http://github.com/CiscoCloud/shipped-buildpack-template-rails.git",
"github_repo_id":43392827,
"drone_repo_enabled":true,"health_check_path":"/"
}

HTTP Request

POST https://api.ciscoshipped.io/projects/<PROJECT_ID>/services

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to create the service

Query Parameters

Parameter Default Description
type - One of “ServiceRepo” or “ServiceImage”. ServiceImages have the minimum attributes to launch a service. ServiceRepos are a superset of a ServiceImages attributes and correspond to services in active development backed by a github repository.
name - The name for the service
image_source - The graphic displayed for this service
deploy_image Inherited from the buildpack The docker image used when deploying this service.
default_cpu Inherited from the buildpack All configurations created from this service will start with this amount of CPU.
ram Inherited from the buildpack All configurations created from this service will start with this amount of ram.
container_port Inherited from the buildpack. The port on which your service listens. In the case of ServiceImages, you’ll need to set this before your container is deployable
buildpack_id - (Only ServiceRepo) The id of the buildpack to use for the ServiceRepo
public - (Only ServiceRepo) Whether or not the created github repository should be public
organization (Only ServiceRepo) The github organization in which to put the repository. Defaults to the authenticated user’s organization
build_image Inherited from the buildpack (Only ServiceRepo) The docker image used to build this service.
build_command Inherited from the buildpack (Only ServiceRepo) The command to run to build your service.
test_command Inherited from the buildpack (Only ServiceRepo) The command to run to test your service.
run_command Inherited from the buildpack (Only ServiceRepo) The command to run to run your service.
health_check_path Inherited from the buildpack (Only ServiceRepo) The endpoint of your application to hit to see if it’s working.
container_shared_directory Inherited from the buildpack (Only ServiceRepo) The mount point within your image for your service code.

Update a service

curl -X PUT 'https://api.ciscoshipped.io/projects/19d87036-532a-11e5-913f-0242ac1100c4/services/4455979b-66e9-11e5-99e0-0242ac110120' -d '{"name": "rails2"}'

Example Response

{
"type": "ServiceRepo",
"project_id":"34a35726-66e9-11e5-99df-0242ac110120",
"id":"4455979b-66e9-11e5-99e0-0242ac110120",
"buildpack_id":"4e0c194a-1c66-11e5-bb2c-a45e60e7c003",
"name":"rails2",
"image_source":"https://api.ciscoshipped.io/cli/static/images/ruby-on-rails-alt.svg",
"build_image":"bradgearon/ruby:2.2.2",
"deploy_image":"bradgearon/ruby:2.2.2",
"repository":"https://github.com/mikejihbe/railssss",
"organization":"",
"public":true,
"default_cpu":1,
"default_ram":512,
"build_command":"/app/bin/build",
"run_command":"/app/bin/run",
"test_command":"/app/bin/test",
"container_port":3000,
"container_shared_directory":"/app",
"bootstrap_template_repo":"http://github.com/CiscoCloud/shipped-buildpack-template-rails.git",
"github_repo_id":43392827,
"drone_repo_enabled":true,"health_check_path":"/"
}

Updates a service for a project, and returns the updated service.

HTTP Request

PUT https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>

URL Parameters

Parameter Description
PROJECT_ID The project id for the service to be updated
SERVICE_ID The service id for the service to be updated

Query Parameters

Parameter Default Description
type - One of “ServiceRepo” or “ServiceImage”. ServiceImages have the minimum attributes to launch a service. ServiceRepos are a superset of a ServiceImages attributes and correspond to services in active development backed by a github repository.
name - The name for the service
image_source - The graphic displayed for this service
deploy_image Inherited from the buildpack The docker image used when deploying this service.
default_cpu Inherited from the buildpack All configurations created from this service will start with this amount of CPU.
ram Inherited from the buildpack All configurations created from this service will start with this amount of ram.
container_port Inherited from the buildpack The port on which your service listens. In the case of ServiceImages, you’ll need to set this before your container is deployable
buildpack_id - (Only ServiceRepo) The id of the buildpack to use for the ServiceRepo
public - (Only ServiceRepo) Whether or not the created github repository should be public
organization (Only ServiceRepo) The github organization in which to put the repository. Defaults to the authenticated user’s organization
build_image Inherited from the buildpack (Only ServiceRepo) The docker image used to build this service.
build_command Inherited from the buildpack (Only ServiceRepo) The command to run to build your service.
test_command Inherited from the buildpack (Only ServiceRepo) The command to run to test your service.
run_command Inherited from the buildpack (Only ServiceRepo) The command to run to run your service.
health_check_path Inherited from the buildpack (Only ServiceRepo) The endpoint of your application to hit to see if it’s working.
container_shared_directory Inherited from the buildpack (Only ServiceRepo) The mount point within your image for your service code.

Delete a project service

Deletes a project service

curl -X DELETE 'https://api.ciscoshipped.io/projects/19d87036-532a-11e5-913f-0242ac1100c4/services/4455979b-66e9-11e5-99e0-0242ac110120'

HTTP Request

DELETE https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>

URL Parameters

Parameter Description
PROJECT_ID The project id for the service
SERVICE_ID The service id to delete

Environments

An environment is a deployable set of configurations for your project. For example, it would be typical in many deployments to have a “Production” environment and a “Staging” environment operating at very different scales. You can create as many of these as you want. Each environment contains a specific configuration for each service in your application that defines global parameters for your application.

List Environments

curl https://api.ciscoshipped.io/projects/2b8dbde6-dd84-11e4-ab36-0090f5d8986c/envs

Example Response

[
   {
      "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "project_id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
      "name":"Staging",
      "description":"Staging env for QA"
   },
   {...},
   {...}
]

Retrieves all environments for a project.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Create an environment

curl https://api.ciscoshipped.io/projects/2b8dbde6-dd84-11e4-ab36-0090f5d8986c/envs -H 
'Content-Type: application/json' -d '{"name": "Staging", "description": "Staging env for QA"}'

Example Response

{
   "id":"b475996d-dd1e-11e4-9917-0090f5d8986c",
   "project_id":"2b8dbde6-dd84-11e4-ab36-0090f5d8986c",
   "name":"Staging",
   "description":"Staging env for QA"
}

Creates a new environment for a project and returns that environment. This has a side effect of creating a configuration for every service in the project with a default deploy target.

HTTP Request

POST https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs

URL Parameters

Parameter Description
PROJECT_ID The id of the project to retrieve

Query Parameters

Parameter Default Description
name - The name of the environment
description - A description of the environment

Releases

A release is a build deployed to a specific environment for a service.

Get all releases

Gets all the releases for an environment

curl https://api.ciscoshipped.io/projects/d6638244-71eb-11e5-863c-0242ac110237/envs/3eecaaae-71ee-11e5-b054-0242ac110238/releases

Example Response

[
  {
    "project_id":"d6638244-71eb-11e5-863c-0242ac110237",
    "service_id":"dc7c6530-71eb-11e5-a1d8-0242ac110264",
    "environment_id":"3eecaaae-71ee-11e5-b054-0242ac110238",
    "config_id":"3eed5b61-71ee-11e5-b056-0242ac110238",
    "release_id":"f3c48e2f-72ce-11e5-9209-0242ac11026c",
    "service_type":"ServiceRepo",
    "deploy_image":"npateriyainsecure/php-hello-world",
    "env_name":"ihbe1",
    "container_port":80,
    "container_cpu":1,
    "container_ram":512,"container_count":1,
    "env_variables":[
        {"name":"PHPTEST1_HOST","value":"https://ihbe1--phptest1--phptest1--bcf5b5.ciscoshipped.io"}
    ],
    "project_name":"phptest1",
    "service_name":"phptest1",
    "commit_id":"",
    "error_msg":"",
    "status":"CleaningUp",
    "user_id":"촶",
    "user_login":"mikejihbe",
    "deployment_id":"d7e5947e-ae88-4263-b44a-5f0556f1e8d8",
    "snapshot_id":"f3c467d3-72ce-11e5-9208-0242ac11026c",
    "marathon_app_id":"ihbe1--phptest1--phptest1--721cf2",
    "health_check_path":"/",
    "health_check_max_failures":0,
    "health_check_protocol":"HTTP",
    "deployed_url_template":"https://%s.ciscoshipped.io",
    "deployed_at":"2015-10-14T23:54:48.324Z"
  },
  {...},
  {...}
]

Retrieves the most recent releases for all services in an environment.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/releases

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get releases
ENV_ID The id of the environment for which to get releases

Get the latest release status

Gets the status of the latest release and all the tasks in it

curl https://api.ciscoshipped.io/projects/d6638244-71eb-11e5-863c-0242ac110237/releases/3eecaaae-71ee-11e5-b054-0242ac110238/deployStatus

Example Response

{
  release: {
    "project_id":"d6638244-71eb-11e5-863c-0242ac110237",
    "service_id":"dc7c6530-71eb-11e5-a1d8-0242ac110264",
    "environment_id":"3eecaaa8-71ee-11e5-b054-0242ac110238",
    "config_id":"3eed5b61-71ee-11e5-b056-0242ac110238",
    "release_id":"3eecaaae-71ee-11e5-b054-0242ac110238",
    "service_type":"ServiceRepo",
    "deploy_image":"npateriyainsecure/php-hello-world",
    "env_name":"ihbe1",
    "container_port":80,
    "container_cpu":1,
    "container_ram":512,"container_count":1,
    "env_variables":[
        {"name":"PHPTEST1_HOST","value":"https://ihbe1--phptest1--phptest1--bcf5b5.ciscoshipped.io"}
    ],
    "project_name":"phptest1",
    "service_name":"phptest1",
    "commit_id":"",
    "error_msg":"",
    "status":"CleaningUp",
    "user_id":"촶",
    "user_login":"mikejihbe",
    "deployment_id":"d7e5947e-ae88-4263-b44a-5f0556f1e8d8",
    "snapshot_id":"f3c467d3-72ce-11e5-9208-0242ac11026c",
    "marathon_app_id":"ihbe1--phptest1--phptest1--721cf2",
    "health_check_path":"/",
    "health_check_max_failures":0,
    "health_check_protocol":"HTTP",
    "deployed_url_template":"https://%s.ciscoshipped.io",
    "deployed_at":"2015-10-14T23:54:48.324Z",
    "failure_count": 0,
    },
    status: {
      staged: 4,
      running: 10,
      healthy: 13,
      unhealthy: 3
    }
}

Retrieves the release requested, and if it’s currently deploying, also returns the statuses of the tasks being deployed

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/<RELEASE_ID>/deployStatus

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to deploy a release
RELEASE_ID The id of the release to fetch, typically the one being deployed

Deploy a new release

Deploys a commit ref for a service to an environment on a project.

HTTP Request

POST https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/services/<SERVICE_ID>/deploy

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to deploy a release
ENV_ID The environment for which to deploy the release
SERVICE_ID The service for which to deploy the release

Query Parameters

Parameter Default Description
commit_id - This is the git ref to be deployed. This ref must exist on the service that is being deployed.

Update a release

A release is a point in time snapshot so update is not valid operation.

Get the status of a release

Gets the current status of releases for a service. This will return a list objects with information on the Marathon instances.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/releases/<RELEASE_ID>/status

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to deploy a release
RELEASE_ID The id of the release for which to get the status

Builds

An individual build is a git commit to a specific service.

Get all project builds

Example Request

curl https://api.ciscoshipped.io/projects/2b8dbde6-dd84-11e4-ab36-0090f5d8986c/builds

Retrieves all builds for all services on a project.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/builds

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get builds

Get all service builds

Retrieves all builds for a service.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>/builds

URL Parameters

Parameter Description
PROJECT_ID The id of the service’s project
SERVICE_ID The id of the service for which to update a build

Get a build log

Retrieves the log for a build.

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>/builds/<BUILD_ID>/log

URL Parameters

Parameter Description
PROJECT_ID The id of the service’s project
SERVICE_ID The id of the build’s service
BUILD_ID The id of the build for which to get the log

Configs

A configuration contains all the instructions to run a service. A service has many configurations, at least one per environment in your project. Each configuration also has an associated deploy target. So to deploy a service to a new target, you’d create a new configuration associated with the service, environment, and deploy target.

List configs

List all the configs in an environment

curl 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/envs/549d4a27-66f5-11e5-b425-0242ac1100de/services/4455979b-66e9-11e5-99e0-0242ac110120/config'

Example Response

[
  {
  "config_id":"549e57c0-66f5-11e5-b427-0242ac1100de",
  "project_id":"34a35726-66e9-11e5-99df-0242ac110120",
  "service_id":"4455979b-66e9-11e5-99e0-0242ac110120",
  "environment_id":"549d4a27-66f5-11e5-b425-0242ac1100de",
  "service_type":"service",
  "deploy_target_id":"31f03bc9-0314-11e5-b9c3-6c4008ad584a",
  "deploy_image":"bradgearon/ruby:2.2.2",
  "container_port":3000,"container_cpu":1,
  "container_ram":512,
  "container_count":1,
  "env_variables":[
    {"name":"RAILSSSS_HOST","value":"newproj--new proj--railssss--967eda.ciscoshipped.io"}
  ],
  "project_name":"new proj",
  "service_name":"railssss",
  "environment_name":"newproj",
  "health_check_path":"",
  "health_check_max_failures":0,
  "health_check_protocol":"HTTP",
  "constraint_names":null,
  "deployed_url_template":"",
  "custom_constraints":[],
  "deploy_constraints":[
    {"name":"1 per host","tag":"unique_hosts","checked":false},
    {"name":"Separate racks","tag":"different_racks","checked":false},
    {"name":"Production hosts","tag":"production","checked":false},
    {"name":"Development hosts","tag":"development","checked":false}
  ],
  "hardware_constraints":[
    {"name":"SSD","tag":"ssd","checked":false},
    {"name":"High Network I/O","tag":"high_io","checked":false},
    {"name":"GPU","tag":"gpu","checked":false}
  ]},
  {...},
  {...},
]

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/config

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment for which to get the configs

Get a config

Retrieves a specific config for a project environment

curl 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/envs/549d4a27-66f5-11e5-b425-0242ac1100de/services/4455979b-66e9-11e5-99e0-0242ac110120/config'

Example Response

  {
  "config_id":"549e57c0-66f5-11e5-b427-0242ac1100de",
  "project_id":"34a35726-66e9-11e5-99df-0242ac110120",
  "service_id":"4455979b-66e9-11e5-99e0-0242ac110120",
  "environment_id":"549d4a27-66f5-11e5-b425-0242ac1100de",
  "service_type":"service",
  "deploy_target_id":"31f03bc9-0314-11e5-b9c3-6c4008ad584a",
  "deploy_image":"bradgearon/ruby:2.2.2",
  "container_port":3000,"container_cpu":1,
  "container_ram":512,
  "container_count":1,
  "env_variables":[
    {"name":"RAILSSSS_HOST","value":"newproj--new proj--railssss--967eda.ciscoshipped.io"}
  ],
  "project_name":"new proj",
  "service_name":"railssss",
  "environment_name":"newproj",
  "health_check_path":"",
  "health_check_max_failures":0,
  "health_check_protocol":"HTTP",
  "constraint_names":null,
  "deployed_url_template":"",
  "custom_constraints":[],
  "deploy_constraints":[
    {"name":"1 per host","tag":"unique_hosts","checked":false},
    {"name":"Separate racks","tag":"different_racks","checked":false},
    {"name":"Production hosts","tag":"production","checked":false},
    {"name":"Development hosts","tag":"development","checked":false}
  ],
  "hardware_constraints":[
    {"name":"SSD","tag":"ssd","checked":false},
    {"name":"High Network I/O","tag":"high_io","checked":false},
    {"name":"GPU","tag":"gpu","checked":false}
  ]
}

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/config/<CONFIG_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment for the config
CONFIG_ID The id of the config to get

Create a config

Creates a config for an environment

curl 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/envs/549d4a27-66f5-11e5-b425-0242ac1100de/services/4455979b-66e9-11e5-99e0-0242ac110120/config' -H 'Content-type: application/json' -d '{"deploy_target_id":"31f03bc9-0314-11e5-b9c3-6c4008ad584a","deploy_image":"bradgearon/ruby:2.2.2","container_port":3000,"container_cpu":1,"container_ram":512,"container_count":1,"env_variables":[{"name":"RAILS_HOST","value":"newproj--new proj--railssss--967eda.ciscoshipped.io"}],"project_name":"new proj","service_name":"rails","environment_name":"newproj","health_check_path":"/","health_check_max_failures":0,"health_check_protocol":"HTTP","constraint_names":[],"deployed_url_template":""}'

Example Response

  {
  "config_id":"549e57c0-66f5-11e5-b427-0242ac1100de",
  "project_id":"34a35726-66e9-11e5-99df-0242ac110120",
  "service_id":"4455979b-66e9-11e5-99e0-0242ac110120",
  "environment_id":"549d4a27-66f5-11e5-b425-0242ac1100de",
  "service_type":"service",
  "deploy_target_id":"31f03bc9-0314-11e5-b9c3-6c4008ad584a",
  "deploy_image":"bradgearon/ruby:2.2.2",
  "container_port":3000,"container_cpu":1,
  "container_ram":512,
  "container_count":1,
  "env_variables":[
    {"name":"RAILSSSS_HOST","value":"newproj--new proj--railssss--967eda.ciscoshipped.io"}
  ],
  "project_name":"new proj",
  "service_name":"railssss",
  "environment_name":"newproj",
  "health_check_path":"",
  "health_check_max_failures":0,
  "health_check_protocol":"HTTP",
  "constraint_names":null,
  "deployed_url_template":"",
  "custom_constraints":[],
  "deploy_constraints":[
    {"name":"1 per host","tag":"unique_hosts","checked":false},
    {"name":"Separate racks","tag":"different_racks","checked":false},
    {"name":"Production hosts","tag":"production","checked":false},
    {"name":"Development hosts","tag":"development","checked":false}
  ],
  "hardware_constraints":[
    {"name":"SSD","tag":"ssd","checked":false},
    {"name":"High Network I/O","tag":"high_io","checked":false},
    {"name":"GPU","tag":"gpu","checked":false}
  ]
}

HTTP Request

POST https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/config

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment for the config

Query Parameters

Parameter Default Description
deploy_target_id - The id of the deploy target for this config
deploy_image - Docker image to start the container
container_port Inherited from the service’s port Port for the service to run on
container_cpu Inherited from the service’s cpu CPU allocation for the container
container_ram Inherited from the service container ram RAM allocation for the container
container_count 1 Number of containers to run this service on
env_variables - Hash of keys/values that will be used as environment variables
health_check_path - The route to hit on your service so we know it’s operating. E.g. /healthcheck
health_check_protocol - http or https
constraint_names - An array of tags that are passed to the backend to handle deployment constraints

Update a config

Updates a config for a project environment, and returns the updated config

curl -X PUT 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/envs/549d4a27-66f5-11e5-b425-0242ac1100de/services/4455979b-66e9-11e5-99e0-0242ac110120/config/4455979b-66e9-11e5-99e0-0242ac110320' -H 'Content-type: application/json' -d '{"deploy_image":"bradgearon/ruby:2.2.4"}'

Example Response

  {
  "config_id":"549e57c0-66f5-11e5-b427-0242ac1100de",
  "project_id":"34a35726-66e9-11e5-99df-0242ac110120",
  "service_id":"4455979b-66e9-11e5-99e0-0242ac110120",
  "environment_id":"549d4a27-66f5-11e5-b425-0242ac1100de",
  "service_type":"service",
  "deploy_target_id":"31f03bc9-0314-11e5-b9c3-6c4008ad584a",
  "deploy_image":"bradgearon/ruby:2.2.4",
  "container_port":3000,"container_cpu":1,
  "container_ram":512,
  "container_count":1,
  "env_variables":[
    {"name":"RAILSSSS_HOST","value":"newproj--new proj--railssss--967eda.ciscoshipped.io"}
  ],
  "project_name":"new proj",
  "service_name":"railssss",
  "environment_name":"newproj",
  "health_check_path":"",
  "health_check_max_failures":0,
  "health_check_protocol":"HTTP",
  "constraint_names":null,
  "deployed_url_template":"",
  "custom_constraints":[],
  "deploy_constraints":[
    {"name":"1 per host","tag":"unique_hosts","checked":false},
    {"name":"Separate racks","tag":"different_racks","checked":false},
    {"name":"Production hosts","tag":"production","checked":false},
    {"name":"Development hosts","tag":"development","checked":false}
  ],
  "hardware_constraints":[
    {"name":"SSD","tag":"ssd","checked":false},
    {"name":"High Network I/O","tag":"high_io","checked":false},
    {"name":"GPU","tag":"gpu","checked":false}
  ]
}

HTTP Request

PUT https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/services/<SERVICE_ID>/config/<CONFIG_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
ENV_ID The environment of the config

Query Parameters

Parameter Default Description
deploy_target_id - The id of the deploy target for this config
deploy_image - Docker image to start the container
container_port - Port for the service to run on
container_cpu - CPU allocation for the container
container_ram - Inherited from the service container ram
container_count - Number of containers to run this service on
env_variables - Hash of keys/values that will be used as environment variables
health_check_protocol - http or https
constraint_names - An array of tags that are passed to the backend to handle deployment constraints

Delete a config

Deletes a config for a project environment

HTTP Request

curl -X DELETE 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/envs/549d4a27-66f5-11e5-b425-0242ac1100de/services/4455979b-66e9-11e5-99e0-0242ac110120/config/549e57c0-66f5-11e5-b427-0242ac1100de'

DELETE https://api.ciscoshipped.io/projects/<PROJECT_ID>/envs/<ENV_ID>/services/<SERVICE_ID>/config/<CONFIG_ID>

URL Parameters

Parameter Description
PROJECT_ID The config’s project
ENV_ID The config’s environment
CONFIG_ID The Id of the config to delete

Deploy Targets

Deploy targets are cloud or on-premise clusters where you want to provision your Shipped services. There are public targets, run by Cisco, but you can also add your own.

For now, these targets must be deployments of Mantl.

List targets

List all the targets available to a project

curl 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/deploy_targets'

Example Response

[
  {
    "deployed_url_template": "https://%s.ciscoshipped.io",
    "id": "31f03bc9-0314-11e5-b9c3-6c4008ad584a",
    "is_public_target": true,
    "name": "Cisco EU - 1",
    "opts": {url: "https://shipped-eu-control-01.ams.shipped-cisco.com/marathon/"},
    "project_id": "31f03bc9-0314-11e5-b9c3-6c4008ad584b",
    "type": "marathon"
  },
  {...},
  {...},
]

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/deploy_targets

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get builds

Create a deploy target

Retrieves a specific config for a project environment

curl 'https://api.ciscoshipped.io/projects/34a35726-66e9-11e5-99df-0242ac110120/deploy_targets' -d 
'{ "deployed_url_template": "http://%s.my-domain.com", "name": "My Datacenter", "opts": {url: "https://my-datacenter.com/marathon/", http_auth: {"user": "<user>", "pass": "<pass>"}, "project_id": "31f03bc9-0314-11e5-b9c3-6c4008ad584b", "type": "marathon" }'

Example Response

{
    "id":"31f03bc9-0314-11e5-b9c3-6c4008ad584d",
    "project_id":"31f03bc9-0314-11e5-b9c3-6c4008ad584b",
    "type":"marathon",
    "name":"AWS",
    "opts":{
        "http_auth":{
            "pass":"<pass>",
            "user":"<user>"
        },
        "url":"http://my-domain.com/marathon/"},
    "deployed_url_template":"http://%s.my-domain.com",
    "is_public_target":false
}

HTTP Request

POST https://api.ciscoshipped.io/projects/<PROJECT_ID>/deploy_targets

URL Parameters

Parameter Description
PROJECT_ID The id of the service’s project
TYPE For future use, for now, this must be “marathon”.
NAME The user friendly identifier for the deploy target
DEPLOYED_URL_TEMPLATE A url origin for deployed apps with a single wildcard value “%s” to be filled in with the marathon app id.
OPTS A json object containing at least a URL attribute for how to reach the deploy target

Policies

A policy contains a set of conditions and actions to perform when those conditions have been met. Conditions consist of a metric, a statistic, a comparison function, and a value. Valid options for each of these are defined below:

List policies

List all the configs in an environment

curl 'https://api.ciscoshipped.io/projects/bc1ed8de-2768-11e6-ba73-0242ac110009/services/b7a387e3-2cc4-11e6-9a4e-0242ac110006/env/df83158c-2768-11e6-ba77-0242ac110009/config/b7a5001f-2cc4-11e6-9a4f-0242ac110006/policies'

Example Response

[
  {
    "id":"3b604da3-2cc5-11e6-91b0-0242ac110005",
    "project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009",
    "service_id":"b7a387e3-2cc4-11e6-9a4e-0242ac110006",
    "env_id":"df83158c-2768-11e6-ba77-0242ac110009",
    "config_id":"b7a5001f-2cc4-11e6-9a4f-0242ac110006",
    "name":"policy name",
    "conditions":[
      {
        "id":"3b60bf25-2cc5-11e6-91b1-0242ac110005",
        "project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009",
        "policy_id":"3b604da3-2cc5-11e6-91b0-0242ac110005",
        "metric":"Load Avg",
        "stat":"avg",
        "duration":0,
        "comparison":"GTE",
        "value":75
      }
    ],
    "actions":[
      {
        "action_id":"234f96c4-2e79-11e6-9f92-0242ac110006",
        "id":"3b6146a5-2cc5-11e6-91b2-0242ac110005",
        "increment":"1","max":"2",
        "name":"",
        "parameters":"map[increment:1 max:2 min: decrement: endpoint:]",
        "policy_id":"3b604da3-2cc5-11e6-91b0-0242ac110005",
        "project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009",
        "type":"SCALE_UP"}
      ]
    },
    {...},
    {...},
]

HTTP Request

GET https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>/env/<ENV_ID>/config/<CONFIG_ID>/policies

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
SERVICE_ID The service this policy applies to
ENV_ID The environment this policy applies to
CONFIG_ID The configuration this policy applies to

Create a policy

Creates a policy for a specific configuration


curl -X POST 'https://api.ciscoshipped.io/projects/bc1ed8de-2768-11e6-ba73-0242ac110009/services/b7a387e3-2cc4-11e6-9a4e-0242ac110006/env/df83158c-2768-11e6-ba77-0242ac110009/config/b7a5001f-2cc4-11e6-9a4f-0242ac110006/policies' -H 'Content-type: application/json' -d '{"name":"new policy","conditions":[{"metric":"Load Avg","stat":"avg","duration":0,"comparison":"LTE","value":3}],"actions":[{"name":"","type":"SCALE_DOWN","increment":"1","max":"2","decrement":"","min":"","endpoint":""}]}'

Example Response

{
  "id":"d288008d-3196-11e6-9a13-0242ac11000d",
  "project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009",
  "service_id":"b7a387e3-2cc4-11e6-9a4e-0242ac110006",
  "env_id":"df83158c-2768-11e6-ba77-0242ac110009",
  "config_id":"b7a5001f-2cc4-11e6-9a4f-0242ac110006",
  "name":"all conditions",
  "conditions":[
    {
      "id":"d28833cc-3196-11e6-9a14-0242ac11000d",
      "project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009",
      "policy_id":"d288008d-3196-11e6-9a13-0242ac11000d",
      "metric":"Load Avg",
      "stat":"avg",
      "duration":0,
      "comparison":"LTE",
      "value":3
    }],
    "actions":[
      {
        "action_id":"d28940a5-3196-11e6-9a1a-0242ac11000d",
        "increment":"1",
        "max":"2",
        "name":"",
        "policy_id":"d288008d-3196-11e6-9a13-0242ac11000d",
        "project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009",
        "type":"SCALE_UP"
      }
    ]
  }

HTTP Request

POST https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>/env/<ENV_ID>/config/<CONFIG_ID>/policies

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
SERVICE_ID The service this policy applies to
ENV_ID The environment this policy applies to
CONFIG_ID The configuration this policy applies to

Query Parameters

Parameter Default Description
name - The name of the policy
conditions - An array of conditions
conditions.metric - A metric this condition is tracking
conditions.stat - The aggregation function to use. For now, must be “avg”
conditions.comparison - One of “GTE”, “LTE”

Update a policy

Updates a specific policy and returns the new result

curl -X PUT 'https://api.ciscoshipped.io/projects/bc1ed8de-2768-11e6-ba73-0242ac110009/services/b7a387e3-2cc4-11e6-9a4e-0242ac110006/env/df83158c-2768-11e6-ba77-0242ac110009/config/b7a5001f-2cc4-11e6-9a4f-0242ac110006/policies/13e2eb4f-2e79-11e6-96f3-0242ac110005' -H 'Content-type: application/json' -d '{"id":"13e2eb4f-2e79-11e6-96f3-0242ac110005","project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009","service_id":"b7a387e3-2cc4-11e6-9a4e-0242ac110006","env_id":"df83158c-2768-11e6-ba77-0242ac110009","config_id":"b7a5001f-2cc4-11e6-9a4f-0242ac110006","name":"Scale Down","conditions":[{"id":"13e31d4a-2e79-11e6-96f4-0242ac110005","project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009","policy_id":"13e2eb4f-2e79-11e6-96f3-0242ac110005","metric":"Load Avg","stat":"avg","duration":0,"comparison":"LTE","value":3}],"actions":[{"action_id":"13e34701-2e79-11e6-96f5-0242ac110005","decrement":"1","min":"1","name":"","policy_id":"13e2eb4f-2e79-11e6-96f3-0242ac110005","project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009","type":"SCALE_DOWN"}],"editingPolicy":false}'

Example Response

{"id":"13e2eb4f-2e79-11e6-96f3-0242ac110005","project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009","service_id":"b7a387e3-2cc4-11e6-9a4e-0242ac110006","env_id":"df83158c-2768-11e6-ba77-0242ac110009","config_id":"b7a5001f-2cc4-11e6-9a4f-0242ac110006","name":"Scale Down","conditions":[{"id":"13e31d4a-2e79-11e6-96f4-0242ac110005","project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009","policy_id":"13e2eb4f-2e79-11e6-96f3-0242ac110005","metric":"Load Avg","stat":"avg","duration":0,"comparison":"LTE","value":3}],"actions":[{"action_id":"13e34701-2e79-11e6-96f5-0242ac110005","decrement":"1","min":"1","name":"","policy_id":"13e2eb4f-2e79-11e6-96f3-0242ac110005","project_id":"bc1ed8de-2768-11e6-ba73-0242ac110009","type":"SCALE_DOWN"}]}

HTTP Request

PUT https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>/envs/<ENV_ID>/config/<CONFIG_ID>/policies/<POLICY_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
SERVICE_ID The service this policy applies to
ENV_ID The environment this policy applies to
CONFIG_ID The configuration this policy applies to
POLICY_ID The id of the policy

Delete a policy

Deletes a specific policy

HTTP Request

curl -X DELETE 'https://api.ciscoshipped.io/projects/bc1ed8de-2768-11e6-ba73-0242ac110009/services/b7a387e3-2cc4-11e6-9a4e-0242ac110006/env/df83158c-2768-11e6-ba77-0242ac110009/config/b7a5001f-2cc4-11e6-9a4f-0242ac110006/policies/13e2eb4f-2e79-11e6-96f3-0242ac110005'

DELETE https://api.ciscoshipped.io/projects/<PROJECT_ID>/services/<SERVICE_ID>/envs/<ENV_ID>/config/<CONFIG_ID>/policies/<POLICY_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the environment’s project
SERVICE_ID The service this policy applies to
ENV_ID The environment this policy applies to
CONFIG_ID The configuration this policy applies to
POLICY_ID The id of the policy

Buildpacks

You can think of Buildpacks as functional starting points for applications in various web frameworks. For example, if you’re building a Ruby on Rails app, we provide a build pack that sets you up with a working, deployable HelloWorld application with reasonable defaults. We suggest you use these build packs as starting points for new applications. If you have an existing application that you’d like to deploy on Shipped, we have instructions on how to do so.

List all buildpacks

curl https://api.ciscoshipped.io/buildpacks?api_token=<TOKEN>

Example Response

[
   {
      "id":"8dc13969-dd18-11e4-aa3b-0090f5d8986c",
      "name":"PHP",
      "image_source":"https://api.ciscoshipped.io/cli/static/images/php.svg",
      "default_build_command":"mkdir -p output; cp *.png *.php output/",
      "default_run_command": "/app/bin/run",
      "default_test_command":"echo noop",
      "default_cpu":1,
      "default_ram": 512,
      "build_image":"bradrydzewski/php:5.5",
      "default_deploy_image":"tutum/apache-php:latest"
      "default_container_port": 3000,
      "container_shared_directory": "/app",
      "bootstrap_template_repo": "http://github.com/CiscoCloud/shipped-buildpack-template-rails.git"
   },
   {...},
   {...}
]

Retrieves a list of all available buildpacks.

HTTP Request

GET https://api.ciscoshipped.io/buildpacks

Get a buildpack

curl https://api.ciscoshipped.io/buildpacks/8dc13969-dd18-11e4-aa3b-0090f5d8986c

Example Response

{
  "id":"8dc13969-dd18-11e4-aa3b-0090f5d8986c",
  "name":"PHP",
  "image_source":"https://api.ciscoshipped.io/cli/static/images/php.svg",
  "default_build_command":"mkdir -p output; cp *.png *.php output/",
  "default_run_command": "/app/bin/run",
  "default_test_command":"echo noop",
  "default_cpu":1,
  "default_ram": 512,
  "build_image":"bradrydzewski/php:5.5",
  "default_deploy_image":"tutum/apache-php:latest"
  "default_container_port": 3000,
  "container_shared_directory": "/app",
  "bootstrap_template_repo": "http://github.com/CiscoCloud/shipped-buildpack-template-rails.git"
}

Retrieves a buildpack.

HTTP Request

GET https://api.ciscoshipped.io/buildpacks/<BUILDPACK_ID>

URL Parameters

Parameter Description
BUILDPACK_ID The ID of the buildpack to retrieve

Invite Tokens

Creating an invite token invites a user to join a Shipped project. It will send emails to each email address submitted and allow them to collaborate with you on your project.

Create an invite token

Creates invite tokens for every email address. This endpoint also sends emails to the invitees.

curl 'https://api.ciscoshipped.io/invite_tokens' -H 'Content-Type: application/json' -d '{"project_id":"34a35726-66e9-11e5-99df-0242ac110120","emails":["mikejihbe@gmail.com"]}'

Example Response

[
  {
    "token":"c490939f-66ff-11e5-9de2-0242ac110121",
    "email":"mikejihbe@gmail.com",
    "inviter_name":"Mike Ihbe",
    "project_id":"34a35726-66e9-11e5-99df-0242ac110120",
    "project_name":"new proj"
  },
  {...}
]

HTTP Request

POST https://api.ciscoshipped.io/invite_tokens

Query Parameters

Parameter Default Description
project_id - The project to invite
emails - Array of email address to invite

Accept an invite

Accepts an invite by resolving an invite token. If authenticated, will add the current user to the project; otherwise, will instruct the client to redirect to the authentication view.

curl 'https://api.ciscoshipped.io/invite_tokens/c490939f-66ff-11e5-9de2-0242ac110121'

Example Response json {"redirect":"/projects/34a35726-66e9-11e5-99df-0242ac110120/builds"}

HTTP Request

GET https://api.ciscoshipped.io/invite_tokens/<INVITE_TOKEN>

URL Parameters

Parameter Description
INVITE_TOKEN The invite token to accept

Users

List users

Retrieves all users in a project

curl 'https://api.ciscoshipped.io/users/for_project/19d87036-532a-11e5-913f-0242ac1100c4'

Example Response

[
  {
    "auth_token":"",
    "id":52534,
    "login":"mikejihbe",
    "avatar_url":"https://avatars.githubusercontent.com/u/52534?v=3",
    "html_url":"https://github.com/mikejihbe",
    "name":"Mike Ihbe",
    "email":"",
    "api_token":""
  },
  {...}
]

HTTP Request

GET https://api.ciscoshipped.io/users/for_project/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project for which to get users

Remove user from a project

Removes a user from a project.

HTTP Request

curl -X DELETE 'https://api.ciscoshipped.io/users/52534/from_project/b646e23d-4687-11e5-a93e-0242ac1100ac'

DELETE https://api.ciscoshipped.io/users/<USER_ID>/from_project/<PROJECT_ID>

URL Parameters

Parameter Description
PROJECT_ID The id of the project from which to delete the user

Get current user

Retrieves the currently authenticated user.

curl https://api.ciscoshipped.io/users/current

Example Response

{
"auth_token":"e131a3282854d9aba0ea4c8856ff4c",
"id":52534,"login":"mikejihbe",
"avatar_url":"https://avatars.githubusercontent.com/u/52534?v=3",
"html_url":"https://github.com/mikejihbe",
"name":"Mike Ihbe",
"email":"mikejihbe@gmail.com",
"api_token":"fgPyCKmxIubeYTNDtjAyRRDedMiyLpru",
"shipped_tips":{
  "builds":true,
  "deploys":true,
  "overview":true,
  "welcome":true
  }
}

HTTP Request

GET https://api.ciscoshipped.io/users/current

Walkthroughs

Setting up a project

If you receive an invitation to log into Shipped, you will automatically be connected to a project.

Otherwise, the first time you log into Shipped, you will be asked to create a project.

1. Give it a name

Enter a unique name for the project.

Name your project

2. Choose buildpacks for the services you’re developing

Select a buildpack

A buildpack is a starting point for a service, giving you a basic, generic framework that is a fully functional and deployable HelloWorld application. You can customize the buildpack at any time.

3. Associate a GitHub repository for that service

Associate a Github repo

You can use a new repository (which Shipped will create automatically) or use an existing repository (which will use your code instead of the buildpack defaults. See adding an existing service.

To create a private repository, you must have a paid Github account with enough capacity to handle the newly created repository.

You need administrative privileges for service setup because Shipped creates a webhook on your behalf that triggers the builds within Shipped.

4. Add any docker packages needed for your application (Optional)

Add docker repo images

Use the available docker packages.

5. Build your project

Build your project

Shipped then:

6. Bootstrap your project for local development

Bootstrap your project

Bootstrap steps

When finished, your app should be running locally and ready for development.

7. Make your first commit

First commit command

Making a commit starts the build. Once it succeeds, it is ready to deploy!.

Creating an environment

Create new environments from the Deploy tab.

Create new environment

1. Give it a name and description,

Create new environment

… then click Add Environment.

This creates a new environment with default settings. The default is to deploy to a Cisco datacenter and grab resources based on the defaults prescribed in the chosen buildpack for each service.

2. Edit environment settings (optional)

From the Deploy tab, click Settings to open the edit panel. This form is for this service within this environment.

Edit environment

From this page you can edit your services resource requirements, deployment image, and healthcheck path.

Edit environment

You can also set deploy targets for each service, allowing your application to be deployed across multiple private and public clouds.

Each deploy target can have it’s own scale, constraints, and environment variables for configuration management.

Deploying a service

After you have setup a project and created an environment, you can deploy a service.

1. Select a service to deploy from the left panel.

Deploy a service

2. Choose a build and environment to deploy.

Deploy a service

Click Deploy to provision your containers according to your environment configurations and launch your application. Once it’s deployed, a link appears that leads to your application.

Deploy complete

Add an existing service

Any service can be run on Shipped – Shipped just needs to know how to build and run your service. You tell it how to do that with two configuration files: drone.yml and dockerfile.

Drone.yml

The .drone.yml is in the root of your services GitHub repository.

Sample .drone.yml

image: docker/image-name
git:
  path: github.com/my/repository
script:
  - echo "build commands"
  - /app/bin/build
  - /app/bin/test
publish:
  docker:
    dockerfile: ./Dockerfile
    docker_host: ip.address.for.drone
    docker_version: 1.4.1
    registry_login_url: $$bintray_repo_login_url
    registry_login: true
    username: $$bintray_user
    password: $$bintray_api_key
    email: $$bintray_user_email
    image_name: $$bintray_image_name
    push_latest: true
    tag: $DRONE_COMMIT
notify:
  webhook:
    urls:
      - "https://api.ciscoshipped.io/webhooks/drone"
    on_success: true
    on_failure: true

Obtain a default Dockerfile from any buildpack-built service from this URL:

https://api.ciscoshipped.io/cli/\<PROJECT_ID>/\<SERVICE_ID>/drone

This yields a yml file that looks similar to the one on the right. Keep the $$ variables, as those are used internally.

Dockerfile

The Dockerfile belongs in the root of your services GitHub repository.

Sample Dockerfile

FROM npateriyainsecure/php-hello-world
EXPOSE 80
WORKDIR /app
COPY . /app

Obtain a default Dockerfile from any buildpack-built service from this URL:

https://api.ciscoshipped.io/cli/\<PROJECT_ID>/\<SERVICE_ID>/Dockerfile

This yields a file that looks similar to the one on the right. You can customize this as much as you want.

Deploying a public Docker image

Any runnable Docker image can be deployed on Shipped. This means you can use public docker containers or container artifacts from your own build process.

1. Edit your project

Edit project

2. Select a Docker image

Click the Repositories tab in the Compose view. Type an image name into the search box and press Enter.

Add a docker image

The results you see come from DockerHub. You can select any runnable image you’d like. Any image that isn’t directly runnable, like an onbuild image, won’t work with Shipped.

Click Select next to the image you want to add.

3. Set variables for Docker image

A form appears, allowing you to edit environment variables for the image.

Deploy image settings

One environment variable will be added for you. Input the name of the variable on the left and the value on the right. To add more variables, click the + (plus). To remove one, click the x.

Click Add when you’re finished adding environment variables.

Build your project

Click Build Project to add the image to your project.

4. Edit Docker image settings

Some images require minimal setup.

From the Deploy tab, select the service on the left that corresponds to your image. Then click Settings.

Deploy image settings

Set the port that the service within the container runs on. For example, with MySQL this setting would be 3306.

Deploy Env Vars

Edit whatever environment variables are required for your Docker image. These are usually outlined in the image repository.

Deploy Env Vars

Edit any other settings you want and save the environment settings at the top.

5. Deploy your service

Now your Docker image is ready to be deployed like any other service.

Adding application policies

1. From the deploy page, click on an environment’s settings

Click Settings

2. Click “Alerting Thresholds”

Then click “Add New Policy”.

Click Alerting Thresholds

3. Fill-in your polciy configuration

Policies consiste of a set of conditions, and a set of actions to be performed if all the conditions are met. Add as many conditions and actions as you’d like.

To change the value being compared in the conditions, drag the metrics on the radar chart above.

All fields in conditions and actions are required.

4. Click save on the policy, then save on the page

Save your policy

Deploying to your own cloud

1. Go to your project settings

Click Settings

2. Click “Deploy Targets”

Then click “Add Deploy Target” and select the correct type from the dropdown.

Click Settings

3. Fill-in your deploy target configuration

Today, this must be a properly configured installation of Mantl.io. In the future, we will support other deployment targets like Kubernetes.

Create Deploy Target

4. Add a configuration to your services

From the Deploy tab, create an environment if one doesn’t exist. Once it does, click “Settings”. Then select “+ New Target” and choose your new target. Then you can edit the configuration.

Click Settings

Inviting collaborators

1. Go to your project settings

Click Settings

2. Click “Add New User”

Click add user

3. Enter emails of new users

Enter Emails

Adding a webhook

1. Go to your project settings

Click Settings

2. Click “Webhooks”, then “Add new webhook”

Click add webhook

3. Configure your webhook

Select the webhook type, then choose which events you want to be notified about. Finally, enter the URL that you want to receive notifications.

Configure webhook