Codebox npm is a serverless npm registry to allow companies that wish to keep their intellectual property. It allows sharing of npm modules within a company but additionally allows access to all of the modules on public npm. One other major difference is that it replaces
npm login authentication to be via github / github enterprise. Users are always required to be authenticated when using codebox as their npm registry.
It is currently compatible with the latest version of the npm & yarn cli.
The quickest way to deploy your own npm registry from your local machine is to follow the following guide.
- A GitHub / GitHub Enterprise application is registered (e.g. for GitHub), you will need the
- You have
AWSenvironment credentials setup with enough access to deploy Serverless resources on your local machine, you can follow the standard guide from Amazon here.
- Latest version of Serverless installed globally (
npm install serverless -gor
yarn global add serverless).
serverless install --url https://github.com/craftship/codebox-npm/tree/0.21.2 --name my-npm-registry- pick whichever name you prefer for your registry
- Setup your environment variables:
export CODEBOX_REGION="eu-west-1" # Set the AWS region you wish your registry to be deployed to export CODEBOX_ADMINS="" # Comma seperated list of github usernames (e.g. "jon,kadi"), these users will be the only ones able to publish export CODEBOX_REGISTRY="https://registry.npmjs.org/" # The NPM mirror you wish to proxy through to export CODEBOX_BUCKET="my-npm-registry-storage" # The name of the bucket in which you wish to store your packages export CODEBOX_GITHUB_URL="https://api.github.com/" # The GitHub / GitHub Enterprise **api** url export CODEBOX_GITHUB_CLIENT_ID="client_id" # The client id for your GitHub application export CODEBOX_GITHUB_SECRET="secret" # The secret for your GitHub application export CODEBOX_RESTRICTED_ORGS="" # OPTIONAL: Comma seperated list of github organisations to only allow access to users in that org (e.g. "craftship,myorg"). Useful if using public GitHub for authentication, as by default all authenticated users would have access.
serverless deploy --stage prod(pick which ever stage you wish)
npm set registry <url>-
<url>being the base url shown in the terminal after deployment completes, such as:
Using it in your Repositories
The easiest way to ensure developers are using the correct private registry url is to setup a
.npmrc file. This contains default settings that npm will pick up on and will ensure the registry is set per repository.
This is especially great for repositories you wish developers to allow publishing and keep private. Here is an example
If a user is doing any
npm operation for the first time in the repository then they will need to
always-auth=true allows yarn to be supported in your project.
npm login Usage
Once you are using the private registry you are required to always be authenticated with npm. This ensures not just anyone can request private packages that are not to be shared with the outside world.
To login you can use the
npm login cli command, if you have 2FA enabled you will need to (when prompted) enter the username in the format of your GitHub username.otp e.g.
jonsharratt.123456. Once logged in it will store a long life token that will be used going forward.
You are now able to use npm commands as normal.
yarn login Usage
The best way to setup yarn authentication is to do an initial
npm login so it can support a 2FA login if you have it enabled.
Once done ensure you have a project based
.npmrc config setup a per the "Using it in your Repositories" guide above. The
always-auth=true option ensures yarn will work with your
Yarn does not require an explicit
yarn login as in this scenario it uses your
.npmrc config instead.
Admins / Publishing Packages
npm publish works as it normally does via the npm CLI. By default all users that authenticate have read only access. If you wish to allow publish rights then you need to set the
CODEBOX_ADMINS environment variable to a comma separated list of GitHub usernames such as
jonsharratt,kadikraman and re-deploy.
Setup with your CI
We recommend creating a GitHub user that can represent your team as a service account. Once created you can then use that account to
npm login to the private registry.
You then need to get the generated token and login url (note the login url is not the same as the registry url). Do this by running
cat ~/.npmrc. As an example you should see an entry that looks like the following:
In your CI tool you can then set the following environment variables (e.g. using the example above):
To allow your CI to access to the npm registry you should have a
.npmrc file in the root of your repository, if not, as mentioned above we recommend doing this.
Then as a pre build step before any
npm install / package installs run the following to inject the authentication url into your
echo "$NPM_REGISTRY_LOGIN_URL:_authToken=$NPM_AUTH_TOKEN" >> .npmrc
Note: You can then reuse this build step for all of your repositories using your private npm registry.
If you are happy with Codebox on the AWS domain and wish to move it to a custom domain, instructions can be found on the AWS website here.
Once you have your custom domain setup you will need to ensure packages already published are migrated by running the following command (supply only the host of your custom domain):
serverless codebox domain --stage yourstage --host custom-domain.com