Getting Started with Wercker Releases

Using Wercker Releases (Limited Availability)

Prerequisites

Before you can push and pull Docker images to and from the Wercker Releases registry:

  • You must have been invited to use this Limited Availability feature. To request an invitation, go to wercker.com.
  • You must have a Wercker username and a Wercker authentication token. If you don't have an authentication token already, see How to get a Wercker Authentication token.
  • You must have access to the Docker CLI (for example, to push and pull images on a local machine, you'll need to have installed Docker on the local machine).

What is Wercker Releases?

Wercker Releases is an Oracle-managed registry that makes it easy for you as a developer to store, share, and manage development artifacts like Docker images. Integration with the Wercker UI and Wercker Clusters enables you to simplify your development to production workflow.

(For the General Availability release of Wercker Releases, support for additional types of development artifacts like jar files and Helm charts is anticipated.)

Wercker Releases runs on Oracle Cloud Infrastructure. Its highly available and scalable architecture ensures you can reliably deploy your applications. So you don't have to worry about operational issues, or scaling the underlying infrastructure.

You use Wercker Releases as a private Docker registry, pushing and pulling Docker images to and from Wercker Releases using the Docker V2 API and the standard Docker command line interface (CLI). Wercker Releases is integrated with Wercker Identity, which provides:

  • easy authentication options (like logging in with your GitHub identity)
  • resource-level control of each repository

When to use Wercker Releases?

If you're using Wercker, you use the Wercker UI to push and pull objects to and from the Wercker Releases registry via an organization to which you have access. That could be an organization you've created, or an organization belonging to another user.

If you're pushing built images as part of a Wercker pipeline, Wercker automatically stores images in the Wercker Releases registry. Similarly, by default, Wercker Clusters will push and pull objects to and from the Wercker Releases registry.

You can also use the Docker CLI to push and pull Docker images to and from the Wercker Releases registry. To use the Docker CLI, you'll first have to obtain an authentication token (see How to push and pull images to and from Wercker Releases using the Docker CLI).

What is a repository in the Wercker UI?

In the Wercker UI, related images in the Wercker Releases registry are shown as grouped into repositories for convenience. A repository groups together different versions of an image with a common name, where each version is identified by a tag. Each repository is owned by an organization. A repository name comprises the name of the owning organization and the name of the images it contains.

For example,the acme-dev-org/hello-world repository is owned by the acme-dev-org organization, and contains images named hello-world. Each image in the acme-dev-org/hello-world repository has a unique tag (for example, 'latest', '4.6.3', '20160823', '7.5.2').

Using the Wercker UI, you can create an empty repository that belongs to an organization, and give it a name. Any images you subsequently push to the Wercker Releases registry that have the same name as the repository are grouped into that repository.

Alternatively, if you push an image to the Wercker Releases registry and a repository with the image's name doesn't already exist, a new repository with that name is created. The repository will belong to the organization that you specify in the push command.

About usernames and organizations in Wercker Releases

In Wercker, organizations are a way to make managing access to applications easier and more efficient. You can convert your Wercker username into an organization (and get a new username for yourself), and you can also create new organizations from scratch. Organization names have to be unique across all of Wercker.

When you create a repository in the Wercker Releases registry, you specify the organization to which the repository belongs.

The repository can only be accessed by users who are members of the organization, either directly or through membership of one of the teams associated with the organization. Only those users who are members of an organization are able to push and pull images to and from repositories belonging to that organization. Note that to push images to a repository, a user must be a member of the Owners team of the organization to which the repository belongs.

About images in Wercker Releases

You can store, share, and manage Docker images in the Wercker Releases registry. A Docker image is a read-only template with instructions for creating a Docker container. A Docker image holds the application that you want Docker to run as a container, along with any dependencies. To create a Docker image, you first create a Dockerfile to describe that application. You then build the Docker image from the Dockerfile. Having created a Docker image, you store it in a Docker registry.

How to create a repository in Wercker Releases

Using the Wercker UI, you can create an empty repository that belongs to an organization, and give it a name. Any images you subsequently push to the Wercker Releases registry that have the same name as the new repository are grouped into that repository.

Having created the new repository, you can push an image to the repository by:

Note that although creating an empty repository can be a convenient placeholder, it is not strictly necessary. If you push an image to the Wercker Releases registry and a repository with the image's name doesn't already exist, a new repository with that name is created.

To create a repository in Wercker Releases:

  1. In the Wercker UI, display the Releases page.
  2. Click Create.
  3. Select the organization that will own the new repository
  4. Specify a name for the new repository click +

You can also use the Wercker REST API to create a repository. See Create a Repository in the REST API documentation.

How to push and pull images to and from Wercker Releases using the Docker CLI

Having built (or otherwise obtained) a Docker image, you can push it to the Wercker Releases registry using the Docker CLI. You can subsequently pull the image from the Wercker Releases registry to run it as a Docker container using the Docker CLI.

How to push images to Wercker Releases using the Docker CLI

To push images to the Wercker Releases registry using the Docker CLI:

  1. If you already have a Wercker authentication token, go to the next step. Otherwise:
    1. In the Wercker UI, display your Profile page, and click Personal tokens.
    2. On the Personal tokens page, specify a name for the new authentication token and click Generate.
    3. Copy the generated token string.
  2. In a terminal window on the client machine running Docker, log in to Wercker Releases by typing docker login wcr.io
  3. When prompted, enter your Wercker username as the username, and your Wercker authentication token as the password.
  4. Locate the image on the client machine that you want to push:
    1. In a terminal window on your client machine, type docker images to list the available images.

      For example:

          
      $ docker images
      REPOSITORY        TAG              IMAGE ID      CREATED       SIZE
      acme-web-app      latest           8e0506e14874  2 hours ago   162.6 MB
      acme-web-app      version1.0       7d9495d03763  2 hours ago   162.6 MB
      <none>            <none>           6ebd328f833d  5 hours ago   162.6 MB
      hello-world       latest           80b84820d442  5 weeks ago   890 B
    2. Find the image on the client machine that you want to push to the Wercker Releases registry.

      In the output of the docker images command, look for the specific image that you want to push. You'll need to uniquely identify this image later, in one of the following ways:

      • using its id
      • using its name and tag, separated by a colon

      For example, you might have an image named acme-web-app on the client machine. In the output of the docker images command, look for the specific acme-web-app image that you want to push. You can uniquely identify that particular image in one of the following ways:

      • using its id (for example, 8e0506e14874)
      • using its name and tag, separated by a colon (for example acme-web-app:latest)
    3. Give a tag to the image that you're going to push to the Wercker Releases registry by typing:
      docker tag <image-identifier> <target-tag>

      where:

      • <image-identifier> uniquely identifies the image, either using the image's id (for example, 8e0506e14874), or the image's name and tag separated by a colon (for example, acme-web-app:latest)
      • <target-tag> is in the format wcr.io/<org-name>/<image-name>:<tag> where:
        • wcr.io is the Wercker Releases registry name
        • <org-name> is the name of the Wercker organization that owns repository to which you want to push the image (for example, acme-dev). Note that your Wercker user must have access to the organization.
        • <image-name> is the name you want to give the image in the Wercker Releases registry (for example, acme-web-app)
        • <tag> is an image tag you want to give the image in the Wercker Releases registry (for example, version2.0.test)

      For example, combining the examples above, you might type:

      docker tag 8e0506e14874 wcr.io/acme-dev/acme-web-app:version2.0.test
  5. Confirm that the Docker image has been correctly tagged on the client machine by typing docker images and verifying that the list of images includes an image with the tag you specified.

    For example:

    $ docker images
    REPOSITORY TAG IMAGE ID CREATED SIZE wcr.io/acme-dev/acme-web-app version2.0.test 8e0506e14874 1 minute ago 162.6 MB acme-web-app latest 8e0506e14874 2 hours ago 162.6 MB acme-web-app version1.0 7d9495d03763 2 hours ago 162.6 MB <none> <none> 6ebd328f833d 5 hours ago 162.6 MB hello-world latest 80b84820d442 5 weeks ago 890 B
  6. Push the Docker image from the client machine to the Wercker Releases registry by typing:
    docker push <target-tag>

    For example:

    docker push wcr.io/acme-dev/acme-web-app:version2.0.test

How to pull images from Wercker Releases using the Docker CLI

To pull images from the Wercker Releases registry using the Docker CLI:

  1. If you already have a Wercker authentication token, go to the next step. Otherwise:
    1. In the Wercker UI, display your Profile page, and click Personal tokens.
    2. On the Personal tokens page, specify a name for the new token and click Generate.
    3. Copy the generated token string.
  2. In a terminal window on the client machine running Docker, log in to the Wercker Releases registry by typing docker login wcr.io
  3. When prompted, enter your Wercker username as the username, and your Wercker authentication token as the password.
  4. Pull the Docker image from the Oracle-managed Docker registry to the client machine by typing:
    docker pull wcr.io/<org-name>/<image-name>:<tag>

    where:

    • wcr.io is the Wercker Releases registry name
    • <org-name> is the name of the Wercker organization that owns the repository from which you want to pull the image (for example, acme-dev). Note that your Wercker user must have access to the organization.
    • <image-name> is the name of the image that you want to pull from the Wercker Releases registry (for example, acme-web-app)
    • <tag> is the tag of the image that you want to pull from the Wercker Releases registry (for example, version2.0.test)

    For example:

    docker pull wcr.io/acme-dev/acme-web-app:version2.0.test

    Note that if you don't specify a <tag> in the docker pull command, Docker pulls the image that has the latest tag.

  5. Confirm that the image has been pulled from the Wercker Releases registry by typing docker images and verifying that the list of images on the client machine now includes the image you just pulled.

    For example:

    $ docker images
    REPOSITORY                    TAG             IMAGE ID          CREATED       SIZE
    wcr.io/acme-dev/acme-web-app  version2.0.test 8e0506e14874      1 minute ago  162.6 MB
    acme-web-app                  latest          8e0506e14874      2 hours ago   162.6 MB
    acme-web-app                  version1.0      7d9495d03763      2 hours ago   162.6 MB
    <none>                        <none>          6ebd328f833d      5 hours ago   162.6 MB
    hello-world                   latest          80b84820d442      5 weeks ago   890 B

How to push and pull images to and from Wercker Releases within Wercker workflows

Having built (or otherwise obtained) a Docker image of an application, you can push it to the Wercker Releases registry from a Wercker workflow. You add an - internal/docker-push: step to the application's wercker.yml file for a particular pipeline. Similarly you can subsequently pull the image from the Wercker Releases registry by adding steps to the application's wercker.yml file.

How to push images to Wercker Releases within a Wercker workflow

To push images to the Wercker Releases registry within a Wercker workflow:

  1. Edit the wercker.yml file for the application.
  2. Add an internal/docker-push: step to the pipeline's steps: section, along with any Docker parameters you want to set, as shown in the example below:
    - internal/docker-push:
        tag: $WERCKER_GIT_BRANCH-$WERCKER_GIT_COMMIT
        working-dir: /pipeline/source
        ports: "8080"
        cmd: ./hello-world
  3. If your build doesn't run on wercker.com, add the repository parameter as follows:
    - internal/docker-push:
        repository: wcr.io/<org_name>/<repository_name>

When you next execute this pipeline on wercker.com, it will push an image to the repository you specified.

If you want to use the Wercker CLI to execute the pipeline, then you must first run wercker login

How to pull images from Wercker Releases within a Wercker workflow

To pull images from the Wercker Releases registry within a Wercker workflow:

  1. Edit the wercker.yml file for the application.
  2. Include a step in the pipeline's steps: section to pull the image, specifying both the Wercker authentication token to use, as well as the image to pull in the format wcr.io/<org-name>/<image-name>:<tag> where:
    • wcr.io as the Wercker Releases registry name
    • <org-name> is the name of the Wercker organization that owns the repository from which you want to pull the image (for example, acme-dev). Note that your Wercker user must have access to the organization.
    • <image-name> is the name of the image that you want to pull from the Wercker Releases registry (for example, acme-web-app)
    • <tag> is the tag of the image that you want to pull from the Wercker Releases registry (for example, version2.0.test)

See Example: Build an application in Wercker, push it to Wercker Releases registry, and deploy it to a Kubernetes cluster created with Wercker Clusters for a fully worked example.

Pushing and pulling images to and from the Wercker Releases registry when deploying an application to a Kubernetes cluster created with Wercker Clusters

If you've used Wercker Clusters to create a Kubernetes cluster on which to deploy an application, you'll typically want to:

  • Define a pipeline in the application's wercker.yml file (sequenced after a build pipeline) to push the application's image to the Wercker Releases registry. The pipeline will include an - internal/docker-push: step that specifies parameter values for repository and tag details.
  • Define a pipeline in the application's wercker.yml file to deploy the application to the cluster according to instructions in a Kubernetes manifest file. The manifest file specifies parameter values for the repository from which to pull the application's image and how to deploy the image as running containers on nodes in the cluster.

See Example: Build an application in Wercker, push it to Wercker Releases registry, and deploy it to a Kubernetes cluster created with Wercker Clusters for a fully worked example.

How to view images and image details in Wercker Releases

To make sure you pull the correct image or to identify images that you no longer need, you can find out detailed information about the images in the Wercker Releases registry.

To view images and image details:

  1. In the Wercker UI, display the Releases page. You see repositories belonging to all the organizations to which you have access, along with the name of the image most recently pushed to each repository and when that image was pushed.
  2. Click the name of the repository that contains the image you're interested in.

    All the tagged images in the repository are shown, and for each image:

    • when it was last modified
    • the user who uploaded it
    • its size
    • a link to download it
    • an option to delete it

You can also use the Wercker REST API to see image details. See Get a Repository in the REST API documentation.

How to delete an image from Wercker Releases

When you no longer need an old image or you simply want to clean up the list of image tags in a repository, you can delete images from the Wercker Releases registry.

To delete an image from the Wercker Releases registry:

  1. In the Wercker UI, display the Releases page. You see repositories belonging to all the organizations to which you have access.
  2. Click the name of the repository from which to delete the image.
  3. Click the Delete icon beside the tagged image and confirm that you want to delete the image.

The image is permanently removed from the Wercker Releases registry.

You can also use the Wercker Releases REST API to delete an image.

How to get a Wercker authentication token

Before you can push and pull Docker images to and from the Wercker Releases registry, you must already have a Wercker username and a Wercker authentication token. If you haven't got a Wercker authentication token, or you've forgotten it, or you're not sure, you can create a new authentication token. You only see the value of the authentication token when you create it, so be sure to copy the token value to a secure location immediately.

Tip: If you do lose or forget the value of the authentication token, you can always create a new authentication token. There's no limit to the number of authentication tokens you can create.

To create a new Wercker authentication token:

  1. Log in to https://app.wercker.com using the user name and password that you provided while creating an account with Wercker.
  2. Click your avatar icon in the top right-hand corner, select Settings to display the Profile page, and select Personal token from the left-hand menu to display the Personal tokens page.
  3. Enter a name for the new Wercker authentication token (for example, my-first-token), and click Generate.

    The value of the new token is shown. For example, fbff5d3f9dfd788... (abbreviated for readability).

  4. Copy the token value and keep it in a secure location, as you won't be able to see it again.
  5. Click Done. The name of the token appears in your list of personal tokens, along with the last few characters of the token value.