.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PINTOD 1p"
.TH PINTOD 1p "2020-05-18" "perl v5.30.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
pintod \- Web interface to a Pinto repository
.SH "VERSION"
.IX Header "VERSION"
version 0.14
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  pintod \-\-root=/path/to/repository [\-\-auth key=value] [\-\-port=N]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`pintod\*(C'\fR provides a web \s-1API\s0 to a Pinto repository.  Clients (like
pinto) can use this \s-1API\s0 to manage and inspect the repository.  In
addition, \f(CW\*(C`pintod\*(C'\fR serves up the distributions within the repository,
so you can use it as the backend for cpan or cpanm.
.PP
Before running \f(CW\*(C`pintod\*(C'\fR you must first create a Pinto repository.  For
example:
.PP
.Vb 1
\&  pinto \-\-root=/path/to/repository init
.Ve
.PP
See pinto for more information about creating a reposiotry.
.SH "ARGUMENTS"
.IX Header "ARGUMENTS"
.IP "\-\-root \s-1PATH\s0" 4
.IX Item "--root PATH"
.PD 0
.IP "\-r \s-1PATH\s0" 4
.IX Item "-r PATH"
.PD
The path to the root directory of the Pinto repository you wish to
serve.  Alternatively, you may set the \f(CW\*(C`PINTO_REPOSITORY_ROOT\*(C'\fR
environment variable.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\-\-auth KEY=VALUE" 4
.IX Item "--auth KEY=VALUE"
Sets an option for the authentication scheme (default is no authentication).
Each time this is used, a key=value pair must follow; one of them must be
\&'backend', which should correspond to a class in the Authen::Simple
namespace. The remaining options will be passed as-is to the authentication
backend.
.Sp
See \*(L"\s-1USING BASIC HTTP AUTHENTICATION\*(R"\s0 for more guidance on enabling
authenticaion with minimal fuss, or see \*(L"\s-1USING OTHER AUTHENTICATION SCHEMES\*(R"\s0
for more complex options.
.IP "\-\-port \s-1INTEGER\s0" 4
.IX Item "--port INTEGER"
.PD 0
.IP "\-p \s-1INTEGER\s0" 4
.IX Item "-p INTEGER"
.PD
Specifies the port number that the server will listen on.  The default is
\&\fB3111\fR.  If you specify a different port, all clients will also have to specify
that port.  So you probably don't want to change the port unless you have
a very good reason.
.IP "other options" 4
.IX Item "other options"
All other options supported by plackup are supported too, such as
\&\f(CW\*(C`\-\-server\*(C'\fR, \f(CW\*(C`\-\-daemonize\*(C'\fR, \f(CW\*(C`\-\-access\-log\*(C'\fR, \f(CW\*(C`\-\-error\-log\*(C'\fR etc.  These will
be passed to Plack::Runner.  By default, \f(CW\*(C`pintod\*(C'\fR uses on the Starman
for the server backend.  Be aware that not all servers support the same options.
.SH "USING BASIC HTTP AUTHENTICATION"
.IX Header "USING BASIC HTTP AUTHENTICATION"
\&\f(CW\*(C`pintod\*(C'\fR ships with Authen::Simple::Passwd, so the easiest way to run
the server with basic \s-1HTTP\s0 authentication is to create a password file using
the \f(CW\*(C`htpasswd\*(C'\fR utility:
.PP
.Vb 1
\&  htpasswd \-c /path/to/htpasswd USER
.Ve
.PP
You will be prompted to enter the password for \f(CW\*(C`USER\*(C'\fR twice.  Then repeat
that command \fBwithout the \-c option\fR for each additional user.   You may
want to put the \fIhtpasswd\fR file inside the top of your repository.
.PP
Then launch pintod like this:
.PP
.Vb 1
\&  pintod \-\-root path/to/repository \-\-auth backend=Passwd \-\-auth path=path/to/htpasswd
.Ve
.PP
If you already have an \fIhtpasswd\fR file somewhere, you may just point to it
directly, or create a symlink.  In any case, the \fIhtpasswd\fR file needs to
be readable by the user that will be running \f(CW\*(C`pintod\*(C'\fR.
.SH "USING OTHER AUTHENTICATION SCHEMES"
.IX Header "USING OTHER AUTHENTICATION SCHEMES"
If you wish to use a different authenticaion scheme, then you'll first need
to install the appropriate Authen::Simple backend module.  Then configure
pintod accordingly.  For example, this would be a valid configuration
for Kerberos:
.PP
.Vb 1
\&  \-\-auth backend=Kerberos \-\-auth realm=REALM.YOUR_COMPANY.COM
.Ve
.PP
and this is how the authentication backend will be constructed:
.PP
.Vb 3
\&  my $auth = Authen::Simple::Kerberos\->new(
\&    realm => \*(AqREALM.YOUR_COMPANY.COM\*(Aq
\&  );
.Ve
.SH "DEPLOYMENT"
.IX Header "DEPLOYMENT"
\&\f(CW\*(C`pintod\*(C'\fR is \s-1PSGI\s0 compatible, running under Plack::Runner by
default.  It will use whatever backend you specify on the command line
or have configured in your environment (defaults to Starman).
.PP
If you wish to add your own middleware and/or customize the backend in
other ways, you can use Pinto::Server in a custom \fI.psgi\fR script like
this:
.PP
.Vb 1
\&    # my\-pintod.psgi
\&
\&    my %opts   = (...);
\&    my $server = Pinto::Server\->new(%opts);
\&    my $app    = $server\->to_app;
\&
\&    # wrap $app with middlewares here and/or
\&    # insert code customized for your backend
\&    # which operates on the $app
.Ve
.PP
Then you may directly launch \fImy\-pintod.psgi\fR using plackup.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
pinto to create and manage a Pinto repository.
.PP
Pinto::Manual for general information on using Pinto.
.PP
Stratopan <http://stratopan.com> for hosting your Pinto repository in the cloud.
.SH "AUTHOR"
.IX Header "AUTHOR"
Jeffrey Ryan Thalhammer <jeff@stratopan.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2015 by Jeffrey Ryan Thalhammer.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.