Frequently Asked Questions

Can't find what you're looking for? Just contact team@stratopan.com any time.


What is a Stratopan repository?

A Stratopan repository is a private CPAN in the cloud. You can fill the repository by pulling modules from the public CPAN or by adding modules that you create yourself. Then you can install those modules from anywhere just by configuring your installer to fetch modules from your Stratopan repository. But unlike the public CPAN, the modules in your Stratopan repository only change when you decide to change them.

Why do I need a private CPAN?

The Perl tool chain always installs the latest version of a module. So if you're using the public CPAN, you never know what versions you are going to get. CPAN authors release new versions every day, which can introduce bugs or break compatibility with your application at any time. But if you use a private CPAN, like Stratopan, then you'll always know exactly which versions of the modules are going to be installed.

What is the difference between a public and a private repository?

Public repositories are visible to anyone, and anyone can download and install modules from it. Private repositories are only visible to their owner, and only the owner can download and install modules from it. For both public and private repositories, only the owner can change the contents of the repository.

How do I install modules from my Stratopan repository?

Simply configure your installer to fetch modules from your Stratopan repository. Each repository is accessible through its URL. For cpanm (recommended), it would look like this:

cpanm --mirror-only --mirror https://stratopan.com/USERNAME/REPOSITORY_NAME/STACK_NAME Some::Module

For a private repository, add your username and access token like this:

cpanm --mirror-only --mirror https://USERNAME:ACCESS_TOKEN@stratopan.com/USERNAME/REPOSITORY_NAME/STACK_NAME Some::Module

Be sure to include the --mirror-only flag to direct cpanm to not use the cpanmetadb to resolve packages. Without this flag, you won't get the versions of the modules you expect, if any.

If you are using cpan as your installer, then it would look like this (after starting the cpan shell):

cpan[1]> o conf urllist https://stratopan.com/USERNAME/REPOSITORY_NAME/STACK_NAME cpan[2]> install Some::Module

And for private repositories with cpan:

cpan[1]> o conf urllist https://USERNAME:ACCESS_TOKEN@stratopan.com/USERNAME/REPOSITORY_NAME/STACK_NAME cpan[2]> install Some::Module

Always use https to ensure your connection is secure. For public repositories, plain http connections will be redirected to an https address. But for private repositories, plain http connections will be denied.

Depending on your setup, the default Perl libraries used by cpanm and cpan may not support HTTP authentication and SSL. In that case, both will usually fallback to using the wget or curl utilities, which do support HTTP authentication and SSL. If you still have connection problems, try installing the LWP::Protocol::https module. Also check that your http_proxy and/or https_proxy environment variables are set correctly if you are connecting through a proxy.

What is a "stack"?

A stack is similar (but not identical) to a branch in a version control system. Within a single repository, you can have several stacks with different sets of Perl modules in them. Stacks allow you to make changes in isolation. You could have different stacks for each phase of development, or for different projects, or for different versions of Perl.

How does Stratopan resolve dependencies?

When you recursively add or pull a distribution to a stack, Stratopan fetches all the modules that are required to complete the entire dependency tree. For each module, Stratopan first checks the version of the module that is already on the stack, if any. If that version is insufficient, then it looks at the latest version of the module in the entire repository, which includes all other stacks. If that version is also insufficient, then Stratopan will fetch the latest version from the public CPAN.

This pattern helps your team stay (or converge) on the same versions of all your dependencies. So if you have multiple stacks in your repository for different teams or projects, then they will tend use the same versions of Perl modules, unless one of them deliberately chooses to use a different one.

What is the "target Perl version"?

When Stratopan needs to fetch a dependency, it first checks the target Perl to determine if that version of Perl provides a satisfactory version of the dependency. If it does not, then Stratopan will start searching for the dependency. But if it does, then Stratopan will ignore the dependency and assumes that it will be provided by your Perl.

You should set the target Perl version to be the version of Perl that you plan to run your application with. If you run your application with multiple versions of Perl, then you should set the target Perl version to be the lowest version that you plan to support. In some cases, however, you may want to use completely separate stacks with different modules for each version of Perl that you support.

The target Perl version in the repositroy settings is the default for all new stacks. However, you can override the default target Perl version for each stack in the stack settings.

How do I change the version of a module?

You can upgrade (or downgrade) the version of a module in a stack by simply pulling another distribution from CPAN to the same stack. Stratopan will replace the current version of the module. If the recursive option is selected, Stratopan will also fetch any dependencies that are required for the replacement. However, Stratopan will not downgrade dependencies when you downgrade a module.

cpanm says it couldn't find a module in my repository. What now?

Stratopan relies on static META files to determine dependencies, and most of the time that works just fine. But Perl also allows module authors to compute depndencies dynamically and customize them for your specific environment. In those rare cases, Stratopan may not automatically pull all the necessary prerequisites for you.

To solve this problem, simply pull whatever modules cpanm reports as missing. At the moment, you'll have to translate the package names reported by cpanm into distribution names for Stratopan. We are working to improve this.

The distribution version I need isn't offered when I pull. Why not?

Some distributions are not available through Stratopan because they are oddly packaged or have invalid metadata. This affects less than 2% of all distributions that have ever been released to CPAN (usually older ones). Module authors will often correct those problems in subequent releases, so you should first consider upgrading if possible.

But if you can't upgrade and the distribution version you want is not offered on Stratopan, then please contact team@stratopan.com and we will help you find a solution. In many cases, we can provide you with a patched version of the distribution that is compatible with Stratopan.

Why can't I add multiple distribution archives with the same name?

Two reasons for that. First, whenever you release software (to Stratopan, CPAN, or anywhere) you are making a contract with downstream consumers to provide a certain version of the code at a certain location. If you change that code by releasing a different version with the same name you are breaking that contract. Second, Stratopan has a built-in version control system that allows you to roll back the stack to a prior state. To make that possible, each distribution archive in the repository must have a unique file name.

The typical solution is to increment the version number of the distribution. There are many possible schemes for managing software version numbers. We recommend adding a build number to each distribution archive. This can be either a timestamp or sequential number (for example, the "942" in Foo-Bar-1.2-942.tar.gz). Most continuous integration systems can do this for you, and it allows you to preserve the usual semantics of module versions.

How do I package my Perl script/library for release to Stratopan?

At a minimum, your script/library must be packed in a .tar.gz or .zip archive and contain a valid META.yml or META.json file that describes the prerequisites (see CPAN::Meta::Spec for the specification of those files.) Most of the time, it will also contain a build script, tests, manifest, readme, and other supporting files.

It's actually a lot easier than it sounds. Most CPAN authors use tools like ExtUtils::MakeMaker or Module::Build or Module::Install or Dist::Zilla to automatically create the customary directory structure and metadata and then pack it all into a distribution archive for you.

How do I use Pinto with Stratopan?

You don't need Pinto to use Stratopan. In fact, Stratopan eliminates the burden of installing, configuring, and maintaining a local Pinto repository. However, we are working on an API so that you can automatically drive Stratopan the same way that can with Pinto.

If you already have a Pinto repository, we can import it into Stratopan. Then you'll be able to accesses your repository from anywhere and you can get all the great visualization features of Stratopan. Just contact team@stratopan.com and we'll be happy to help with that.