BZLIB/PLANET.plt - A Local PLANET Proxy/Repository Server

PLT's planet system is great - if you want to install a planet module, you just declare it in the code, and it will automatically manage the download and the install for you, without you having to separately run another module installation programs like Perl's CPAN, Ruby's GEM, PHP's PEAR, etc.

However, planet can still be improved. Specifically, as there is currently only a single central repository, you might experience some inconvenient server outage from time to time. And it is difficult to take advantage of the planet's automatic code distribution power unless you plan on releasing the code for public consumption.

That is - until today.

BZLIB/PLANET.plt is designed to solve exactly the issue of a single planet repository. Going forward, you can install bzlib/planet and run a local planet proxy and repository. bzlib/planet is, of course as usual, available via planet under LGPL ;)

Usage

bzlib/planet contains a proxy server that you can setup and run. The first thing to do is to install it via require:

(require (planet bzlib/planet/proxy)) 

After you have installed proxy, you can start the proxy server via:

(parameterize ((current-command-line-arguments #("-r" "/path/to/local/planet/repo" "-p" "9000")))
    (start!))

Alternatively, you can also choose to start it via the included unix script (in the root directory of the installed location for bzlib/planet.plt) called "proxy" if you are in Unix or Mac OSX. And you can start it with something like:

# assume you are in the package root directory
# you might have to run chmod +x proxy first 
$ chmod +x proxy 
$ ./proxy -r </path/to/local/planet/repo> -p <port=9000>

which will parameterize the command line arguments and call start! for you.

The -r argument points to the local repository path - it defaults to /var/data/plt/planet-repo, and can be controlled via -r or via environment variable named BZLIB_PLANET_REPO_PATH. Make sure the path you have created exists.

The -p argument holds the port number that the server will bind against, and it defaults to 9000.

PLT Scheme Planet Configuration

To have your DrScheme or mzscheme call the planet proxy instead of the central planet repository, on version 4.2.3 or later, you can do so via the environent variable PLTPLANETURL. So let's say you have your planet proxy running on http://planet-proxy:9000, you should then set the environment variable of PLTPLANETURL to http://planet-proxy:9000.

If you are running a prior version of PLT, you can make manual modifications to the collects/planet/config.ss, and change the parameter HTTP-DOWNLOAD-SERVLET-URL to the url of your planet proxy.

Proxy Server Behavior

That's all you have to do to setup and use the proxy. Your regular require statements would do exactly the same thing with the proxy. When you make a request of an uninstalled module, the planet module system will now call the proxy server, and the proxy server will check to see if the package is available locally, if so, and if the version constraint matches, the package will be sent to the planet module system, otherwise, the proxy server will make a call to the central repository to make the request. If the central repository holds the module, it will be downloaded, stored in the repository and sent the to planet module system.

Hence, subsequent calls will not require another trip to the central repository. This decouples the proxy from the central repository so you do not need to maintain a live internet connection. The downside is that the download count on the central repository for your module will no longer be accurate going forward ;)

Private Packages

A derived benefit for running a local planet proxy is that you now can take advantage of the automatic code distribution power without having to make your code publicly available, i.e., you can release private code via planet now.

The way to do it is to simply create the appropriate directory structures, and drop your planet packages in them.

The planet repository have the following directory structures:
/<planet-user>/<package-name>/<major-version>/<minor-version>/<package-name>. As an example, bzlib/planet.plt has the following directory structure: /bzlib/planet.plt/1/0/planet.plt. So just drop your packages in the appropriate directories, and the proxy will treat them as if they were released through the central repository.

There are other enhancements that we can add to the package, such as mirroring the central repository, or automate the drop process, etc. I would love to hear them if you have them. For now - enjoy.