quay/static/partials/guide.html

<div class="container content-container">
  <div class="alert alert-warning">Warning: Quay requires docker version 0.6.2 or higher to work</div>

  <h2>User Guide</h2>
  <div class="user-guide container">
    <h3>Signing into Quay <span class="label label-default">Setup</span></h3>
    <div class="container">
      To setup your Docker client for pushing to Quay, login with your credentials:
      <br><br>
      <pre>$ sudo docker login quay.io

Login against server at https://quay.io/v1/
Username: myusername
Password: mypassword
Email: my@email.com</pre>
    </div>
    <br>   

    <h3>Pushing a repository to Quay <span class="label label-success">Requires Write Access</span></h3>
    <div class="container">
      In order to push a repository to Quay, it must be <b>tagged</b> with the <b>quay.io</b> domain and the namespace under which it will live:
      <br><br>
      <pre>sudo docker tag <i>0u123imageid</i> quay.io/<i>username/repo_name</i></pre>
      <br>
      Once tagged, the repository can be pushed to Quay:<br><br>
      <pre>sudo docker push quay.io/<i>username/repo_name</i></pre>
    </div>
    <br>

    <h3>Pulling a repository from Quay</h3>
    <div class="container">
      <div class="alert alert-info">Note: <b>Private</b> repositories require you to be <b>logged in</b> or the pull will fail. See above for how to sign into Quay if you have never done so before. </div>
      To pull a repository from Quay, run the following command:
      <br><br>
      <pre>sudo docker pull quay.io/<i>username/repo_name</i></pre>
    </div>
    <br>

    <h3>Granting and managing permissions to users <span class="label label-info">Requires Admin Access</span></h3>
    <div class="container">
      <div class="description-overview">Quay allows a repository to be shared any number of users and to grant those users any level of permissions for a repository</div>

      <ul class="description-list">
        <li>Permissions for a repository can be granted and managed in the repository's admin interface
        <li><b>Adding a user:</b> Type that user's username in the "Add New User..." field, and select the user
        <li><b>Changing permissions:</b> A user's permissions (read, read/write or admin) can be changed by clicking the field to the right of the user
        <li><b>Removing a user:</b> A user can be removed from the list by clicking the <b>X</b> and then clicking <b>Delete</b>
      </ul>

    </div>
    <br>

    <h3>Using robot accounts <span class="label label-info">Requires Admin Access</span></h3>
    <div class="container">
      <div class="description-overview">
        There are many circumstances where permissions for repositories need to be shared across those repositories (continuous integration, etc).
        To support this case, Quay allows the use of <b>robot accounts</b> which can be created in the user/organization's admin view and can be
        shared by multiple repositories that are owned by that user or organization.
      </div>

      <ul class="description-list">
        <li>Robot accounts can be managed in the user or organization admin's interface
        <li><b>Adding a robot account:</b> Click "Create Robot Account" and enter a name for the account. The username will become <b>namespace+accountname</b> where "namespace" is the name of the user or organiaztion.
        <li><b>Setting permissions:</b> Permissions can be granted to a robot account in a repository by adding that account like any other user or team.
        <li><b>Deleting a robot account:</b> A robot account can be deleted by clicking the <b>X</b> and then clicking <b>Delete</b>
        <li><b>Using a robot account:</b> To use the robot account, the following credentials can be used:
        <dl class="dl-horizontal">
          <dt>Username</dt><dd>namespace+accountname (Example: mycompany+deploy)</dd>
          <dt>Password</dt><dd>(token value can be found by clicking on the robot account in the admin panel)</dd>
          <dt>Email</dt><dd>This value is ignored, any value may be used.</dd>
        </dl>
      </ul>
    </div>

    <h3>Using access tokens in place of users <span class="label label-info">Requires Admin Access</span></h3>
    <div class="container">
      <div class="description-overview">
        For per-repository token authentication, Quay allows the use of <b>access tokens</b> which can be created on a repository and have read and/or write
        permissions, without any passwords.
      </div>

      <ul class="description-list">
        <li>Tokens can be managed in the repository's admin interface
        <li><b>Adding a token:</b> Enter a user-readable description in the "New token description" field
        <li><b>Changing permissions:</b> A token's permissions (read or read/write) can be changed by clicking the field to the right of the token
        <li><b>Deleting a token:</b> A token can be deleted by clicking the <b>X</b> and then clicking <b>Delete</b>
        <li><b>Using a token:</b> To use the token, the following credentials can be used:
        <dl class="dl-horizontal">
          <dt>Username</dt><dd>$token</dd>
          <dt>Password</dt><dd>(token value can be found by clicking on the token)</dd>
          <dt>Email</dt><dd>This value is ignored, any value may be used.</dd>
        </dl>
      </ul>
    </div>

    <a name="#post-hook"></a>
    <h3>Using push webhooks <span class="label label-info">Requires Admin Access</span></h3>
    <div class="container">
      A repository can have one or more <b>push webhooks</b> setup, which will be invoked whenever <u>a successful push occurs</u>. Webhooks can be managed from the repository's admin interface.
      <br><br> A webhook will be invoked
      as an HTTP <b>POST</b> to the specified URL, with a JSON body describing the push:<br><br>
      <pre>
{
  <span class="code-info" title="The number of images pushed" bs-tooltip="tooltip.title">"pushed_image_count"</span>: 2,
  <span class="code-info" title="The name of the repository (without its namespace)" bs-tooltip="tooltip.title">"name"</span>: "ubuntu",
  <span class="code-info" title="The full name of the repository" bs-tooltip="tooltip.title">"repository"</span>:"devtable/ubuntu",
  <span class="code-info" title="The URL at which the repository can be pulled by Docker" bs-tooltip="tooltip.title">"docker_url"</span>: "quay.io/devtable/ubuntu",
  <span class="code-info" title="Map of updated tag names to their latest image IDs" bs-tooltip="tooltip.title">"updated_tags"</span>: {
    "latest": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc"
  },
  <span class="code-info" title="The namespace of the repository" bs-tooltip="tooltip.title">"namespace"</span>: "devtable",
  <span class="code-info" title="Whether the repository is public or private" bs-tooltip="tooltip.title">"visibility"</span>: "private",
  <span class="code-info" title="The Quay URL for the repository" bs-tooltip="tooltip.title">"homepage"</span>: "https://quay.io/repository/devtable/ubuntu"
}
</pre>
    </div>
  </div>
</div>