package_cloud 0.2.43 → 0.2.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bd8d70baa95dc0392b7628081e7ada402add8d1b
-  data.tar.gz: b11a15ec9e89258aa65014ba8d0b8d4618080aed
+  metadata.gz: 7a62b096fe5f34a03b636c6e23e85f0f594d60bb
+  data.tar.gz: 4434346fce72a318222c0d837db7889ed438805b
 SHA512:
-  metadata.gz: daa87bc509eec63173f9f0b416cff5fba27219fda4a8be4aba9fcfb6b10803266ce0514c8b548ad4451ce649f22c7b16d9f370431a9b8328683e641c6d0efca0
-  data.tar.gz: 57ff22ab7445689ecb7d41b3759b8ab1b020dbd6ffcf7baac9e2e577084a1b5baddba8873b4c9ac62fa51af316b221146dcb53d3710ce6cd43d2fb7fec489a81
+  metadata.gz: a2f0caf82796b4486293e2083c83919c22731800a191ea0dd6cd51abcf82a781f56d9557cca49022488d9cbc56fd4528419f3ec5f8fe15b49494b9066960b6ce
+  data.tar.gz: 6830a9268a95f8a66d565d42867a40bb108c05bd0783f5d6c9e9f1948051ebe5cfb95b3e8a44c390cfdb4c20a7758a2d01d29fc81951b938a3def8f09216ac84

data/README.md

@@ -1,29 +1,412 @@
-# PackageCloud
+# packagecloud CLI
 
-TODO: Write a gem description
+Greetings! Welcome to the [packagecloud](https://packagecloud.io) command line
+client, `package_cloud`.
 
-## Installation
-
-Add this line to your application's Gemfile:
+The `package_cloud` command line client allows you to easily:
 
-    gem 'package_cloud'
+* Create Debian, RPM, RubyGem, Python, and Maven package repositories on [packagecloud](https://packagecloud.io).
+* Upload Debian, RPM, RubyGem, Python, and Java JAR/WAR packages to your repositories.
+* [Delete packages](https://packagecloud.io/docs#yank_pkg).
+* [Promote packages](https://packagecloud.io/docs#promote_pkg) between repositories.
+* Upload a package signing GPG key.
+* Create and delete [master and read
+  tokens](https://packagecloud.io/docs#token_auth) to control repository
+  access.
 
-And then execute:
+This tool is intended to be used on the command line either manually or in an
+automated environment (like a build or CI process).
 
-    $ bundle
+## Installation
 
-Or install it yourself as:
+Simply run:
 
     $ gem install package_cloud
 
+to install the command line client.
+
+You can now run `package_cloud` from the command line to see the help message
+displayed.
+
 ## Usage
 
-TODO: Write usage instructions here
+### Getting help
+
+You can run `package_cloud help` to get general help information about the
+supported commands.
+
+You can also get help information for specific commands by running
+`package_cloud help [command]`. For example, to get help on pushing a package
+you can run: `package_cloud help push`.
+
+Additional documentation is also available on our [documentation
+page](https://packagecloud.io/docs).
+
+You can interact with our system programmatically as well by using our
+[API](https://packagecloud.io/docs/api).
+
+### Creating a repository
+
+You can create a package repository named 'example' on [packagecloud](https://packagecloud.io) by running:
+
+```
+$ package_cloud repository create example
+```
+
+### Pushing a package
+
+You can upload Debian, RPM, RubyGem, Python, or Java packages to any
+repository you've created by using the `push` command.
+
+Most package types require specifying a `distribution/version` pair when
+uploading. See the examples that follow for more information.
+
+Please note that packages will be available for download via the packagecloud web UI
+immediately after they are uploaded, but they will not necessarily be
+available for installation via a package manager immediately. This is because
+our system rengenerates the repository metadata needed by package managers as a
+background job on our system. Jobs are added to a queue and processed.
+Processing time depends on the number of packages in your repository and the
+number of reindex jobs in front of yours.
+
+The following examples will show an example user name of `example-user` and a repository
+name of `example-repository`.
+
+After the examples below, there will be an additional section documenting
+important optional parameters you can specify when pushing packages.
+
+#### Uploading a Debian package
+
+You can upload a Debian package found at the path `/tmp/example.deb` for Ubuntu Xenial by running:
+
+```
+$ package_cloud push example-user/example-repository/ubuntu/xenial /tmp/example.deb
+```
+
+This command will upload `/tmp/example.deb` to the `example-repository`
+repository owned by `example-user` as an Ubuntu Xenial package.
+
+We also support Debian source packages (DSCs). You can upload a
+`/tmp/example.dsc` for Ubuntu Xenial by running:
+
+```
+$ package_cloud push example-user/example-repository/ubuntu/xenial /tmp/example.dsc
+```
+
+Note that all files associated with the DSC (like source tarballs, patches,
+etc) must reside in the same directory as the DSC itself.
+
+You can specify other Ubuntu or Debian versions. Consult the [full list of
+combinations](https://packagecloud.io/docs#os_distro_version) to find the one
+you need.
+
+#### Uploading an RPM package
+
+You can upload an RPM package found at the path `/tmp/example.rpm` for CentOS
+6 by running:
+
+```
+$ package_cloud push example-user/example-repository/el/6 /tmp/example.rpm
+```
+
+This command will upload `/tmp/example.rpm` to the `example-repository`
+repository owned by `example-user` as a CentOS 6 package.
+
+You can specify other CentOS, Fedora, Oracle, Scientific Linux, or SUSE versions.
+Consult the
+[full list of combinations](https://packagecloud.io/docs#os_distro_version)
+to find the one you need.
+
+#### Uploading a RubyGem package
+
+You can upload a RubyGem package found at the path `/tmp/example.gem` by
+running:
+
+```
+$ package_cloud push example-user/example-repository /tmp/example.gem
+```
+
+This command will upload `/tmp/example.gem` to the `example-repository`
+repository owned by `example-user` as a RubyGem package.
+
+Note that unlike all other package types, RubyGems do not require any
+additional specification on upload.
+
+#### Uploading a Python package
+
+You can upload a Python package found at the path `/tmp/example.whl` by
+running:
+
+```
+$ package_cloud push example-user/example-repository/python /tmp/example.whl
+```
+
+This command will upload `/tmp/example.whl` to the `example-repository`
+repository owned by `example-user` as a Python package.
+
+We also support Python eggs and source distributions. Note that recent
+versions of pip no longer support installing Python eggs and will fail to find
+eggs in PyPI repositories.
+
+If you'd like to upload a Python egg despite this, you can do so by running:
+
+```
+$ package_cloud push example-user/example-repository/python /tmp/example.egg
+```
+
+#### Uploading a Java JAR or WAR package
+
+You can upload a Java JAR package found at the path `/tmp/example.jar` by
+running:
+
+```
+$ package_cloud push example-user/example-repository/java/maven2 /tmp/example.jar
+```
+
+WAR files can be uploaded the same way.
+
+It is important to note that in some cases (for example: 'fat JARs', or JARs
+without `pom.xml` files, etc) our system will not be able to automatically detect
+the [Maven coordinates](https://maven.apache.org/pom.html#Maven_Coordinates).
+In these cases you will receive an error, and you should specify the
+coordinates manually on the command line:
+
+```
+$ package_cloud push example-user/example-repository/java/maven2 /tmp/example.jar --coordinates=com.mygroup:packagename:1.0.2
+```
+
+#### Additional options
+
+There are a few additional options you can use to fine tune package upload for
+more advanced use cases:
+
+* `--skip-file-ext-validation` - The CLI will attempt to verify the package's
+  file extension. In some cases, this may be unwanted (for example, when
+  uploading a randomly generated file name). You can ask the CLI to avoid
+  checking the file extension by specifying this flag.
+* `--yes` - When uploading multiple packages the CLI will prompt the user to
+  verify their request by typing 'y'. You can skip the prompt by passing this
+  flag.
+* `--skip-errors` - Sometimes a mass upload of a directory full of packages
+  may fail or be canceled by the user. If you want to re-upload all files
+  without having to manually remove files you have already uploaded, you can
+  use this flag to skip the duplicate file errors and force the CLI to
+  continue uploading packages.
+* `--coordinates` - This flag is used for Java JARs or WARs which do not have
+  an internal `pom.xml` specifying the Maven coordinates. You can specify your
+  own Maven coordinates for this file using this flag: `--coordinates=com.mygroup:packagename:1.0.2`.
+* `--config` - This flag is used to specify a custom configuration file path
+  for the CLI. This file specifies the website URL and your API token. This is
+  default to `~/.packagecloud`.
+* `--url` - This flag is sued to specify a custom URL as the packagecloud
+  server. This option is used by packagecloud:enterprise customers to point to
+  their installation.
+* `--verbose` - This flag is used to generate additional debug information for
+  push operations and is very useful if submitting a bug report to
+  packagecloud :)
+
+### Deleting a package
+
+You can remove a package by using the `yank` command. You will need to specify
+the full filename of the package and the distribution / version pair (except
+for RubyGems).
+
+Removing a package will
+make the package immediately inaccessable from the packagecloud web UI, but it
+may take a few moments for the package to be removed from the repository
+metadata because removals trigger a reindex of the repository.
+
+#### Deleting a Debian package
+
+You can delete a Debian package named `example_1.0.1-1_amd64.deb` that was
+uploaded for Ubuntu Xenial from the repository `example-repository` owned by
+the user `example-user` by running the following command:
+
+```
+$ package_cloud yank example-user/example-repository/ubuntu/xenial example_1.0.1-1_amd64.deb
+```
+
+This will delete the package and trigger a reindex of the repository's
+metadata.
+
+#### Deleting an RPM package
+
+You can delete an RPM package named `example-1.0-1.x86_64.rpm' that was
+uploaded for CentOS 6 from the repository `example-repository` owned by
+the user `example-user` by running the following command:
+
+```
+$ package_cloud yank example-user/example-repository/el/6 example-1.0-1.x86_64.rpm
+```
+
+This will delete the package and trigger a reindex of the repository's
+metadata.
+
+#### Deleting a RubyGem package
+
+You can delete a RubyGem package named `example-1.0.gem' from the
+repository `example-repository` owned by the user `example-user`
+by running the following command:
+
+```
+$ package_cloud yank example-user/example-repository example-1.0.gem
+```
+
+This will delete the package and trigger a reindex of the repository's
+metadata.
+
+#### Deleting a Python package
+
+You can delete a Python package named `example-1.0.1.whl` from the repository
+`example-repository` owned by the user `example-user` by running the following
+command:
+
+```
+$ package_cloud yank example-user/example-repository example-1.0.1.whl
+```
+
+This will delete the package and trigger a reindex of the repository's metadata.
+Python eggs and sdists can be deleted in a similar manner.
+
+
+#### Deleting a Java package
+
+You can delete a Java package named `example-1.0.3.jar` from the repository
+`example-repository` owned by the user `example-user` by running the following
+command:
+
+```
+$ package_cloud yank example-user/example-repository example-1.0.3.jar
+```
+
+This will delete the package and trigger a reindex of the repository's
+metadata. WARs can be deleted in a similar manner.
+
+### GPG Keys
+
+Some package managers use [GPG keys](https://packagecloud.io/docs#gpg)
+to verify that a package was created by the author and not an impersonator.
+
+If you sign your packages with a GPG key before you upload them to
+packagecloud, your package will still be signed when the user downloads it.
+
+In these cases, especially with YUM repositories, it is useful to upload the
+public GPG key that can verify the package you signed. When a user installs
+your repository, the associated GPG key will be installed on their system and
+used for verifying the package.
+
+The follow sections will illustrate how to upload, list, and delete GPG keys.
+
+#### Uploading a package signing GPG key
+
+To upload a GPG key located on
+your system at `/tmp/gpg.key` for the repository `example-repository` owned by
+the user `example-user`, you can run the following command:
+
+```
+$ package_cloud gpg_key create example-user/example-repository /tmp/gpg.key
+```
+
+Note that if you attempt to upload a private key to packagecloud, we will
+extract only the public key component. The private key will then be discarded.
+We do not store or persist private keys at all.
+
+#### Listing GPG keys associated with a repository
+
+You can list the GPG keys associated with the repository `example-repository`
+owned by user `example-user` by running the following command:
+
+```
+$ package_cloud gpg_key list example-user/example-repository
+```
+
+The key name specified in the output of this command is the key name you should
+specify when deleting the key.
+
+#### Deleting GPG keys associated with a repository
+
+You can delete the GPG key named
+`example-user-example-repository-56D06.pub.gpg` associated with the repository
+named `example-repository` and owned by the user `example-user` by running the
+following command:
+
+```
+$ package_cloud gpg_key destroy example-user/example-repository example-user-example-repository-56D06.pub.gpg
+```
+
+You can get the key name for a key you'd like to delete by using the GPG key
+list command above.
+
+### Promoting packages between repositories
+
+Package promotion is a feature which can be used to easily move packages
+between repositories. This is useful for moving a package from a private
+staging repository to a public production ready repository during a software release
+workflow.
+
+To move a package named `example_1.0-1_amd64.deb` from the user
+`example-user`'s repository named `repo1` over to the same users repository
+named `repo2`, you would issue the following command:
+
+```
+$ package_cloud promote example-user/repo1/ubuntu/xenial example_1.0-1_amd64.deb example-user/repo2
+```
+
+After the package is moved, a reindex will be triggered for both `repo1` and
+`repo2`.
+
+### Creating, deleting, and listing master and read tokens
+
+The [token authentication](https://packagecloud.io/docs/#token_auth) system
+used for repositories allows fine grained access control of repositories.
+
+Master tokens can be used just for creating additional read tokens. Master
+tokens themselves do not provide read access to a repository. Deleting
+a master token automatically deletes all associated read tokens.
+
+A typical use case for our token system would be a SaaS service distributing
+a monitoring agent who wants to control download access to their repository.
+
+A master token can be created per customer that signs up and read tokens
+associated with the generated master token can be assigned per system. Then,
+the read tokens can be deleted one at a time (to disable access on a
+per-machine basis) or completely by deleting the associated master token.
+
+#### Creating master tokens
+
+Following from the example explained in the previous section, 
+you can create a master token name "Example-Token" for the repository
+`example-repository` owned by the user `example-user` by running the following
+command:
+
+```
+$ package_cloud master_token create example-user/example-repository Example-Token
+```
+
+#### Listing master tokens
+
+You can list all master tokens associated with the repository
+`example-repository` owned by the user `example-user` by running the following
+command:
+
+```
+$ package_cloud master_token list example-user/example-repository
+```
+
+#### Deleting master tokens
+
+You can delete the token named `Example-Token` associated with the
+repository `example-repository` owned by the user `example-user` by running
+the following command:
+
+```
+$ package_cloud master_token destroy example-user/example-repository Example-Token
+```
+
+This will also automatically delete all read tokens associated with this
+master token, thereby revoking read access to the repository with those
+tokens.
 
-## Contributing
+## Still need help?
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Feel free to reach out to [support@packagecloud.io](mailto:support@packagecloud.io) with questions.

data/lib/package_cloud/cli.rb

@@ -12,9 +12,9 @@ module PackageCloud
     autoload :GpgKey,      "package_cloud/cli/gpg_key"
 
     class Base < Thor
-      class_option "config"
-      class_option "url"
-      class_option "verbose"
+      class_option "config", :desc => "Specify a path to config file containing your API token and URL; default is ~/.packagecloud"
+      class_option "url", :desc => "Specify the website URL to use; default is https://packagecloud.io. Useful for packagecloud:enterprise users."
+      class_option "verbose", :type => :boolean, :desc => "Enable verbose mode."
 
       private
         def get_valid(prompt)

data/lib/package_cloud/cli/entry.rb

@@ -64,11 +64,20 @@ module PackageCloud
       end
 
       desc "push user/repo[/distro/version] /path/to/packages",
-           "push package(s) to repository (in distro/version if required)"
-      option "skip-file-ext-validation", :type => :boolean
-      option "yes", :type => :boolean
-      option "skip-errors", :type => :boolean
-      option "coordinates", :type => :string
+           "Push package(s) to repository (in distro/version, if required). Optional settings shown above."
+
+      option "skip-file-ext-validation", :type => :boolean,
+                                         :desc => "Skip checking validation of the file extension. Package upload will be attempted even if the extension is unrecognized."
+
+      option "yes", :type => :boolean,
+                    :desc => "Automatically answer 'yes' prompted during package push. Useful for automating uploads."
+
+      option "skip-errors", :type => :boolean,
+                            :desc => "Skip errors encountered during a package push and continue pushing the next package."
+
+      option "coordinates", :type => :string,
+                            :desc => "Specify the exact maven coordinates to use for a JAR. Useful for JARs without coordinates, 'fat JARs', and WARs."
+
       def push(repo, package_file, *package_files)
         total_time = Benchmark.measure do
           ARGV.clear # otherwise gets explodes

data/lib/package_cloud/version.rb

@@ -1,7 +1,7 @@
 module PackageCloud
   MAJOR_VERSION = "0"
   MINOR_VERSION = "2"
-  PATCH_VERSION = "43"
+  PATCH_VERSION = "44"
 
   VERSION = [MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION].join(".")
 end

data/package_cloud.gemspec

@@ -8,8 +8,9 @@ Gem::Specification.new do |spec|
   spec.version       = PackageCloud::VERSION
   spec.authors       = ["Joe Damato"]
   spec.email         = ["support@packagecloud.io"]
-  spec.description   = %q{https://packagecloud.io}
-  spec.summary       = %q{https://packagecloud.io}
+  spec.description   = %q{The https://packagecloud.io CLI for uploading Debian, RPM, RubyGem, Python, and Java packages. Check our website or the RubyDoc documentation for detailed information.}
+  spec.summary       = %q{The https://packagecloud.io CLI for uploading Debian, RPM, RubyGem, Python, and Java packages. Check our website or the RubyDoc documentation for detailed information.}
+
   spec.homepage      = "https://packagecloud.io"
   spec.license       = "MIT"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: package_cloud
 version: !ruby/object:Gem::Version
-  version: 0.2.43
+  version: 0.2.44
 platform: ruby
 authors:
 - Joe Damato
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-06-07 00:00:00.000000000 Z
+date: 2017-08-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -108,7 +108,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: https://packagecloud.io
+description: The https://packagecloud.io CLI for uploading Debian, RPM, RubyGem, Python,
+  and Java packages. Check our website or the RubyDoc documentation for detailed information.
 email:
 - support@packagecloud.io
 executables:
@@ -165,5 +166,6 @@ rubyforge_project:
 rubygems_version: 2.4.4
 signing_key: 
 specification_version: 4
-summary: https://packagecloud.io
+summary: The https://packagecloud.io CLI for uploading Debian, RPM, RubyGem, Python,
+  and Java packages. Check our website or the RubyDoc documentation for detailed information.
 test_files: []