Mojo::Darkpan - A Mojolicious web service frontend leveraging OrePAN2
Mojo::Darkpan is a webservice build on Mojolicious to frontend OrePAN2. This module was inspired by OrePAN2::Server but built on Mojolicious to take advantage of it's robust framework of tools. A good bit of the documentation was also taken from OrePAN2::Server as the functionality is similar if not identical.
# start a server with default configurations on port 8080
darkpan --port 8080
# start a server with AD backed basic auth
# config.json
{
"basic_auth": {
"Realm Name": {
"host": "ldaps://my.ldap.server.org",
"port": 636,
"basedn": "DC=my,DC=compoany,DC=org",
"binddn": "bind_name",
"bindpw": "bond_pw",
"filter": "(&(objectCategory=*)(sAMAccountName=%s)(|(objectClass=user)(objectClass=group)))"
}
}
}
darkpan --config ./config.json
- -c,--config default: undef: JSON configuration file location
- -p,--port default: 3000: Web application port
- /publish or /authenquery: POST path(s) for releasing packages, set as the upload_uri in your .pause file
- /list: JSON list of packages and info about them
- /reindex: Force OrePAN2 to do a index all modules and recreate the 02packages.details file.
- /darkpan (may differ if you set a custom path): Directory listing of the repository. This is the path to reference as your mirror or set the PERL_CARTON_MIRROR env var
Configurations can be done using environment variables or by creating a json config file.
Environment variables are at a higher order than values set in the json configuration file and will take precedence if set. The DARKPAN_CONFIG_FILE env variable can be set instead of using the command line option to denote the path of the config file.
- DARKPAN_CONFIG_FILE: Location of a json configuration file, same as passing the --config option
- DARKPAN_DIRECTORY: Directory where uploads will be stored.
- DARKPAN_PATH: URL path to function as cpan repository resolver/mirror endpoint.
- DARKPAN_COMPRESS_INDEX: Setting whether to compress (gzip) the 02packages.details.txt file.
- DARKPAN_AUTH_REALM: Basic auth realm name. This variable needs to be set to enable parsing of additional auth settings using the following the format DARKPAN_AUTH_[setting].
- DARKPAN_AUTH_[setting]: Additional basic auth settings can be passed using this format. The settings will be parsed and applied to your basic auth configurations. See Mojolicious::Plugin::BasicAuthPlus for additional details on configurations.
The config.json file contains customizations for the darkpan web application. It can be referenced by absolute path or relative to where the application is run from.
{
"directory": "darkpan",
"compress_index": true,
"path": "darkpan",
"basic_auth": {
"Realm Name": {
"host": "ldaps://my.ldap.server.org",
"port": 636,
"basedn": "DC=my,DC=compoany,DC=org",
"binddn": "bind_name",
"bindpw": "bond_pw",
"filter": "(&(objectCategory=*)(sAMAccountName=%s)(|(objectClass=user)(objectClass=group)))"
}
}
}
- directory default: darkpan: Directory where uploads will be stored.
- path default: darkpan: URL path to function as cpan repository resolver/mirror endpoint.
- compress_index default: true: Setting whether to compress (gzip) the 02packages.details.txt file.
- basic_auth default: undef: Basic authentication settings, see configurations for Mojolicious::Plugin::BasicAuthPlus. When not provided no authentication is necessary to post modules to the service.
Authentication is handled by Mojolicious::Plugin::BasicAuthPlus. To configure basic auth, see the configuration options for Mojolicious::Plugin::BasicAuthPlus and add your settings to the basic auth section of the config.json file.
Publishing to darkpan can be done using a post request and a URL to git or bitbucket repo.
#upload git managed module to my darkpan by curl
curl --data-urlencode 'module=git+ssh://git@mygit/home/git/repos/MyModule.git' --data-urlencode 'author=reshingleton' http://localhost:3000/publish
curl --data-urlencode 'module=git+file:///home/rshingleton/project/MyModule.git' --data-urlencode 'author=reshingleton' http://localhost:3000/publish
curl --data-urlencode '[email protected]:rshingleton/perl-module-test.git' --data-urlencode 'author=reshingleton' http://localhost:3000/publish
Publishing with a local file
#upload file from disk via curl
curl -F '[email protected]' http://localhost:3000/publish
The module parameter can also be an HTTP url. see OrePAN2::Injector for additional details.
curl --data-urlencode 'module=https://cpan.metacpan.org/authors/id/O/OA/OALDERS/OrePAN2-0.48.tar.gz' --data-urlencode 'author=OALDERS' http://localhost:3000/publish
Publishing with Minilla
Minilla is a cpan authoring tool, see Minilla for more details.
Add a reference to a pause configruation file in your minil.toml that points to your darkpan instance. The configuration can reference a relative path as follows:
[release]
pause_config=".pause"
The .pause file is a configuration file for uploading modules to CPAN or your own Darkpan Repository. See CPAN::Uploader for more detail.
upload_uri http://my-darkpan.server/publish
user myUsername
password myPassword
** if you don't set the upload_uri, you will upload to CPAN
If basic auth is enabled, the username and password set in the .pause file will be used as basic auth credentials.
See cpanm for additional details.
# check CPAN and your Darkpan server
cpanm --mirror http://my-darkpan.server/darkpan
# check for packages from only your Darkpan server
cpanm --mirror-only http://my-darkpan.server/darkpan
cpanm --from http://my-darkpan.server/darkpan
See cpm for additional details.
# resolve distribution names from DARKPAN/modules/02packages.details.txt.gz
# and fetch distibutions from DARKPAN/authors/id/...
> cpm install --resolver 02packages,http://example.com/darkpan Your::Module
# use darkpan first, and if it fails, use metadb and normal CPAN
> cpm install --resolver 02packages,http://my-darkpan.server/darkpan --resolver metadb Your::Module
See carton for additional details.
# in the cpanfile
# local mirror (darkpan)
requires 'Plack', '== 0.9981',
dist => 'MYCOMPANY/Plack-0.9981-p1.tar.gz',
mirror => 'http://my-darkpan.server/darkpan';
Carton also uses an (undocumented) environment variable PERL_CARTON_MIRROR that will enable you to add your Darkpan server to its list of resolvers. Carton will install from your Darkpan and from the default CPAN mirror.
PERL_CARTON_MIRROR=http://my-darkpan.server/darkpan carton install
Copyright (C) rshingleton.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
rshingleton [email protected]