Todo
- Add all package specific format icons
- Add note re: differences between manual package upload and upstream proxying
- Add image(s) for API key creation
- Add image and overview for successful package pull
Setting up your Cloudsmith account and adding a package
This guide will help you get started with Cloudsmith. Using this guide you will:
- Sign up for your Cloudsmith account.
- Create your Workspace.
- Create your first repository.
- Create an Upstream for your repository.
- Add a package to your repository.
Package Formats
This guide uses the
npmpackage manager as an example, but the steps below are applicable for all supported package formats. Format-specific instructions are available within the Cloudsmith web app.
Step 1: Creating your Cloudsmith account
To create your Cloudsmith account, firstly navigate to the Cloudsmith account sign up page. Enter your email address, and click "Continue".
On the next screen, enter your details, password and password confirmation and ensure you have accepted the service terms and conditions. Once these fields are complete click "Continue".
Step 1.1: Email verification and Log in
A verification email containing a log in link will be sent to the email address used for account sign up. Open this email and click the link to complete the account sign up process. This link will take you to the account log in page. Enter your email and password and click "Continue" to log into your Cloudsmith account:
Step 2: Create your Workspace
When logging in to your account for the first time, you are prompted to create your Workspace. Enter the name for your Workspace (this can be changed later if required), and click "Continue".
Step 3: Creating your first repository
You are now asked to create a repository. Enter the name of your repository (this can be changed later if required) and click "Continue".
Repository overview view
Once you have created your repository, the repository overview will be shown:
Step 4: Adding an Upstream proxy
Before a package can be added to your repository, you first need to add an Upstream. In this example, we will add an upstream for npm (the package manager for Node.JS), but the steps are broadly similar for all upstreams.
Click the "Upstreams" menu item to open the Upstreams view.
Adding Upstreams
For security reasons you may be required to re-enter your credentials when adding an Upstream.
The Upstreams view presents a list of the most common Upstream proxies. Select the Upstream you wish to add, or if you can't see the required Upstream from the list provided, click the "Add Upstream Proxy" button to show the full list of available Upstreams.
Once the Upstream is added it will read as Configured. In the example below, the NPMJS.com upstream has been added for the repository.
All enabled Upstreams will be displayed in the Upstream Proxying table below the list, providing the ability to disable or delete Upstreams as required.
Step 5: Generating an API Key
Private repositories
By default repositories are private when created. This means that they are not publicly accessible and authentication is required to add or remove packages from them.
By default repositories are private, and authentication is required to add or remove packages to/from a repository. There are a number of ways to authenticate these actions, and for this example we will use a personal API Key.
Before a package can be added to the repository from an enabled Upstream, an personal API key must be generated.
To generate an API Key:
- Select your User Profile icon in the top right hand corner, and select "Personal API Keys" from the menu:
- In the API Keys view, Click the "Create API Key" button.
- The generated API Key will be displayed. This API Key must be stored securely, as it will not be possible to retrieve this once the pop up has been closed.
Step 6: Adding a package to your repository
Repository Package Formats
Repositories are multi-format - you can add packages from multiple formats (Upstreams) to a single repository.
Return to your repository view by clicking the Cloudsmith Icon in the top left hand corner, selecting your Workspace from the Workspace list, clicking on the "Repositories" menu item and then selecting your repository.
To add a package, click either the "Add a Package" or "Push/Pull Packages" buttons.
The Package Format selection view
The Package format selection view is now shown, displaying a list of package formats that you can add to your repository. If your preferred format is not shown, click "Show all formats" to show the complete list of package formats that can be added to a repository.
Package format specific instructions
Clicking your required Package format will present the relevant package format-specific set up instructions. Follow these instructions to pull down your first package. An example for NPM is shown below:
Format specific instructions can also be viewed below: