.\" =*= License: BSD =*=
.TH GITANO-SETUP 1
.SH NAME
gitano\-setup \- set up a Gitano instance
.SH SYNOPSIS
.B gitano\-setup
.RB [ -h ]
.RB [ --help ]
.RB [ --usage ]
.RB [ ANSWER-FILE ...]
.SH DESCRIPTION
.B gitano-setup
creates the basic repository setup for a Gitano instance.
Gitano is a git repository management system.
It provides repository creation, user administration, and access control.
.PP
.B gitano-setup
is an interactive tool where if it has any questions for you, it will
visit each answers file in turn until it finds the answer.
This means that for automation purposes you can specify multiple answers
files with the earlier ones overriding the later ones.
.PP
In summary, the behaviour is as follows:
.PP
The repository root is created if it does not exist, and a
.I gitano-admin.git
repository is created within it.
Said repository is populated with the example administration repository
rules and an admin user and group.
.SS "Answer files"
Answer files contain key value pairs which are used to answer the questions
which
.B gitano-setup
would otherwise prompt for.  If the setting
.I setup.batch
is set, then
.B gitano-setup
will operate in batch mode, rather than interactively.  The format is as
follows:
.PP
.nf
.RS
key.name "value"
.RE
.fi
.PP
Valid keys and the
meaning of their values are:
.TP
.BR setup.batch
Operate in batch mode if set at all.
.TP
.BR paths.home
Home directory for the Gitano management user.  This defaults to the
.B HOME
environment variable.
.TP
.BR paths.ssh
The
.I .ssh
directory for the Gitano management user.  This defaults to the value of
.B paths.home
with
.I /.ssh
appended.
.TP
.BR paths.pubkey
The path to a public SSH key to be used for the newly created user with
.I gitano-admin
rights in the new Gitano instance.  This defaults to the value of the
.I paths.ssh
variable plus
.I id_rsa.pub
etc if present.  Normally you would set this to the path to your public key
so that you will have administration rights upon creation of the instance.
.TP
.BR paths.repos
The path to the repository store for the new Gitano instance.  This defaults
to the value of
.I paths.home
with
.I /repos
appended to it.
.TP
.BR admin.username
The username for the administrator of the new Gitano instance.  This defaults
to
.I admin
and is only relevant for rulesets inside Gitano.
.TP
.BR admin.realname
The real name for the administrator of the new Gitano instance.  This defaults
to
.I Administrator
and is only relevant inside the Gitano instance as it will be used to indicate
the name of the committer of administration changes.
.TP
.BR admin.email
The email address of the administrator of the new Gitano instance.  This
defaults to
.I admin@administrator.local
and is only relevant inside the Gitano instance as it will be used to indicate
the email address of the comitter of administration changes.
.TP
.BR site.name
The site name used in greetings and messages from Gitano.  This defaults to
.I a random Gitano instance
and should always start with a lowercase letter since it will be used in
sentences such as
.B Welcome to
.I a random Gitano instance
or those with similar forms.
.TP
.BR log.prefix
The log prefix for the Gitano instance.  This defaults to
.I gitano
and is used in messages from Gitano.  Lines generated by Gitano will be
prefixed with the log prefix in square brackets.  For example:
.PP
.nf
.RS
[example] CRIT: Repository creation is not permitted.
[example] FATAL: Ruleset denied action.  Sorry.
.RE
.fi
.PP
.SH OPTIONS
.TP
.BR \-h ", " \-\-help ", " \-\-usage
Print out a usage summary for the program.
.SH EXAMPLE
To set up a new Gitano instance:
.PP
.nf
.RS
sudo adduser git
sudo su - git
gitano-setup
.RE
.fi
.PP
There you go.