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>


    <h3>Deleting a tag <span class="label label-info">Requires Admin Access</span></h3>
    <div class="container">
      <div class="description-overview">
        A specific tag and all its images can be deleted by right clicking on the tag in the repository history tree and choosing "Delete Tag". This will delete the tag and any images <b>unique to it</b>. Images will not be deleted until all tags sharing them are deleted.
      </div>
    </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="context-tooltip" title="The number of images pushed" bs-tooltip="tooltip.title">"pushed_image_count"</span>: 2,
  <span class="context-tooltip" title="The name of the repository (without its namespace)" bs-tooltip="tooltip.title">"name"</span>: "ubuntu",
  <span class="context-tooltip" title="The full name of the repository" bs-tooltip="tooltip.title">"repository"</span>:"devtable/ubuntu",
  <span class="context-tooltip" 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="context-tooltip" title="Map of updated tag names to their latest image IDs" bs-tooltip="tooltip.title">"updated_tags"</span>: {
    "latest": "b750fe79269d2ec9a3c593ef05b4332b1d1a02a62b4accb2c21d589ff2f5f2dc"
  },
  <span class="context-tooltip" title="The namespace of the repository" bs-tooltip="tooltip.title">"namespace"</span>: "devtable",
  <span class="context-tooltip" title="Whether the repository is public or private" bs-tooltip="tooltip.title">"visibility"</span>: "private",
  <span class="context-tooltip" title="The Quay URL for the repository" bs-tooltip="tooltip.title">"homepage"</span>: "https://quay.io/repository/devtable/ubuntu"
}
</pre>
    </div>
  </div>
</div>