Hex Repository

Hex is a package manager for the BEAM ecosystem, any language that compiles to run on the BEAM VM, such as elixir and Erlang, can be used to build Hex packages.

With Hex, developers can create, share, and manage packages for their projects.

For more information on Hex, please see:

• Hex: Public repository for hosting and managing Hex packages
• HexDocs: HexDoxs is where Hex packages host their documentation.
• Publishing a Hex package: How to Publish a Hex package.

In the following examples:

Upload a Package

Publishing a Hex package to Cloudsmith involves several steps, including adding Cloudsmith to your project's repository list, configuring metadata in the mix.exs file, and finally, using the Mix client to publish the package.

📘

Mix

Mix is a build tool that ships with Elixir. For an introduction on Elixir and Mix, see introduction to Mix. You can also read about how hex packages work with mix at Hex Mix Usage.

Assuming you have mix already installed, it is straightforward to add a Cloudsmith-based hex repository.

Add and Configure a Cloudsmith Repository

First, you'll need to set some environment variables to assist in the process, replacing OWNER with your Cloudsmith account's organization and REPOSITORY with the name of your Cloudsmith repository:

export CLOUDSMITH_API_KEY='YOUR-API-KEY'
export CLOUDSMITH_API_HOST='https://api.cloudsmith.io'
export CLOUDSMITH_REPOSITORY='OWNER/REPOSITORY'

While documented as optional, it's necessary to obtain the repository's fingerprint via Cloudsmith's API. This fingerprint ensures secure communication between your project and Cloudsmith.

Use the command below to Cloudsmith's API to retrieve the active RSA key (aka its fingerprint) for the Cloudsmith Repository:

export FINGERPRINT=$(curl -s -H "X-Api-Key: ${CLOUDSMITH_API_KEY}" ${CLOUDSMITH_API_HOST}/v1/repos/${CLOUDSMITH_REPOSITORY}/rsa/ | jq -r '.ssh_fingerprint')

Next, use Mix's hex.repo add command to add your Cloudsmith repository:

mix hex.repo add REPOSITORY https://hex.cloudsmith.io/${CLOUDSMITH_REPOSITORY} --auth-key $CLOUDSMITH_API_KEY --fetch-public-key SHA256:${FINGERPRINT}

Replace REPOSITORY with the name of your Cloudsmith repository.

🚧

Install hex task

Note: If you get the error 'The task "hex.repo" could not be found' you will first need to install the hex task in mix. (For more information, see the Hex usage documentation.) Run:

mix local.hex

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs

Configure the HEX Package

To configure your Hex package for publishing to your Cloudsmith repository, follow these steps:

1. Open mix.exs: Locate and open the mix.exs file of the Hex package you intend to publish to Cloudsmith.
2. Add defp Function: Within the mix.exs file, add a defp function to define the Cloudsmith repository. This function specifies the repository URL and authentication details.
3. Here's an example of how to add the defp function:

defp hex do
    [
      api_url: "https://hex.cloudsmith.io/hex/OWNER/REPOSITORY",
      api_key: "API-KEY"
    ]
  end

Replace OWNER with your Cloudsmith account's organization and REPOSITORY with the name of your Cloudsmith repository. Additionally, replace API-KEY with your Cloudsmith API key.

Next, integrate with Mix Tasks: After adding the defp function, the project function needs to have the hex and project variables defined.

1. Open mix.exs: Locate and open the mix.exs file of the Hex package you intend to publish to Cloudsmith.
2. Locate the project function and populate the hex and package variables. Here's an example of what to add to the project function:

def project do
  [
    ...
    package: package(),
    hex: hex()
    ...
  ]
end

Publish your HEX package

Once you've configured your Hex package to publish to your Cloudsmith repository, you can proceed with the publishing process. Follow these steps to publish your HEX package:

1. Navigate to Your Package Folder: Open a terminal or command prompt and navigate to the top-level directory of your package.
   Shell

   cd /path/to/your/package
   

2. Execute the Publish Command: Use the mix hex.publish package command to initiate the publishing process. This command automatically packages your project and publishes it to the configured Cloudsmith repository.
   Shell

   mix hex.publish package
   

3. Follow On-screen Instructions: Follow any on-screen prompts or instructions to complete the publishing process.
   These prompts may include confirming the package details and agreeing to publish.

By following these steps, you'll successfully publish your HEX package to your Cloudsmith repository. Remember to review the published package on your Cloudsmith dashboard to verify its availability and correctness.

Upload via the Cloudsmith CLI

For full details of how to install and setup the Cloudsmith CLI, see Command Line Interface.

The command to upload a Hex package via the Cloudsmith CLI is:

cloudsmith push hex OWNER/REPOSITORY PACKAGE_NAME.tar

Replace OWNER with your Cloudsmith account's organization and REPOSITORY with the name of your Cloudsmith repository.

Upload via Cloudsmith Website

Please see Upload a Package for details of how to upload via the Website UI.

Example Project

For examples of what your project should look like for packaging and publishing/uploading, please have a look at our examples repository (on GitHub). We'll supplement these with more detailed guidance later but otherwise, just ask - we're here to help!

Download or Installing a Package

Setup

Before you can install modules from your Cloudsmith repository you'll need to add the repository. Follow the steps above "Add and Configure a Cloudsmith Repository". Your entitlement token can be used as the API key.

Download a Package

You can download a package by using mix's fetch command:

mix hex.package fetch PACKAGE-NAME PACKAGE-VERSION --repo REPOSITORY

Replace REPOSITORY with the name of your Cloudsmith repository.

For example, to download version 1.0.0 of the 'jason' module:

mix hex.package fetch jason 1.0.0 --repo REPOSITORY

Replace REPOSITORY with the name of your Cloudsmith repository.

🚧

Entitlement Tokens, User Credentials and API-Keys should be treated as secrets, and you should ensure that you do not commit them in configurations files along with source code or expose them in any logs

Adding a Cloudsmith Package as a Dependency

To incorporate a package hosted on Cloudsmith into your project, you need to modify your mix.exs file. Follow these steps to add the Cloudsmith repository as a dependency:

1. Locate and open the mix.exs file of your Hex project in a text editor.
2. Edit the Dependencies Function: Within the deps function of mix.exs, add an entry for your Cloudsmith package. Ensure to replace PACKAGE_NAME, VERSION, and REPOSITORY with your specific details.
   Shell

   defp deps do
       [ 
         {:PACKAGE_NAME, "~> VERSION", repo: "REPOSITORY"},
      ]
     end
   

3. Run the mix publish command and it will pull in the dependencies
   Shell

   mix hex.publish package
   

Security Scanning

Supported
Please see our Security Scanning documentation for further information.

Upstream Proxying / Caching

Configurable Proxying Caching
You can configure upstream Hex repositories that you wish to use for packages that are not available in your Cloudsmith repository. In addition, you can also choose to cache any requested packages for future use.

Please see our Upstream Proxying documentation for further instructions.

📘

Hex upstreams are in Early Access.

Troubleshooting

Please see the Troubleshooting page for further help and information.