package App::lcpan::Manual::Tutorial::200_SettingUpAMiniCPAN;

# DATE
# VERSION

1;
# ABSTRACT: Setting up a local "mini" CPAN mirror

__END__

=pod

=encoding UTF-8

=head1 NAME

App::lcpan::Manual::Tutorial::200_SettingUpAMiniCPAN - Setting up a local "mini" CPAN mirror

=head1 VERSION

version 1.058.000

=head1 SETTING UP YOUR LOCAL MINICPAN MIRROR

Setting up a local "mini" CPAN mirror is as easy as:

 % lcpan update --verbose

and after a few hours of downloading and indexing, your local CPAN mirror is
ready at ~/cpan.

However, usually you might want to tweak a few things first.

=head2 Customize CPAN and index location

To customize the location of the mirror instead of using the default F<~/cpan>,
put this in F<~/lcpan.conf> (or F</etc/lcpan.conf> if you run as root):

 cpan = /path/to/cpan

and make sure the path exists and is writable.

If you don't want a config file, you can specify C<--cpan> option everytime you
invoke C<lcpan>.

The index database that lcpan creates is usually put in the top-level directory
of the CPAN mirror (F<~/cpan/index.db>). It is beneficial to put the index on a
fast SSD instead of the slower harddisk, so if you happen to put the CPAN mirror
on a harddisk, you can point the index to a different location using this
configuration line:

 index_name=/ssd/partition/index.db

=head2 Exclude some files

Some releases are big (tens to over 100MB files) and some contain a lot (like
thousands) of modules. This will require more time to download and index. I
usually put these lines in my configuration:

 [subcommand=update]

 ; don't download files over 200MB
 max_file_size=209715200

 ; don't index these files which contain thousands of autogenerated modules
 skip_index_file_patterns = ^eBay-API-\d
 skip_index_file_patterns = ^Google-Ads-GoogleAds-Client-\d
 skip_index_file_patterns = ^Google-Ads-AdWords-Client-\d
 skip_index_file_patterns = ^GOOGLE-ADWORDS-PERL-CLIENT-\d
 skip_index_file_patterns = ^Microsoft-AdCenter-\d
 skip_index_file_patterns = ^Paws-\d
 skip_index_file_patterns = ^VMOMI-\d

because I never use those modules. You might or might not want to do the same.
For me, those lines cut down the amount of indexing from several hours to to
under an hour.

=head1 USING YOUR LOCAL MINICPAN MIRROR

=head2 Installing modules

To install modules from your local mirror, you can use:

 % cpanm --mirror file:/path/to/cpan --mirror-only -n MODULE::NAME

The C<--mirror-only> option prevents C<cpanm> from falling back to a normal,
remote CPAN mirror, since your mini CPAN already contains "the whole" CPAN
(well, all the indexed modules anyway).

You can make the mirror accessible via HTTP/HTTPS using whatever webserver
software or framework, e.g. http://localhost:2020/ or https://example.com/cpan/,
and use it just as easily with C<cpanm>:

 % cpanm --mirror http://localhost:2020/ --mirror-only -n MODULE::NAME

=head2 Querying information

C<lcpan> is created so you can query the database for various information. For
example, to find out what modules the C<Dist-Zilla> distribution requires:

 % lcpan deps Dist-Zilla
 % lcpan deps Dist::Zilla  ;# same thing
 % lcpan deps -R Dist::Zilla --exclude-core

If you want to query over HTTP, there's L<App::lcpan::Daemon> which is a L<PSGI>
application you can run with a PSGI-compliant webserver.

If you want a nice web interface like L<MetaCPAN|https://metacpan.org> for your
local mini CPAN mirror, currently you're out of luck. Maybe I or someone else
will get around to it. Note that you can also setup a MetaCPAN of your own, but
it's more involved.

=head1 AUTHOR

perlancar <perlancar@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2020 by perlancar@cpan.org.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut