=head1 NAME

=for bif-doc #hubadmin

bif-doc-hub - how to manage remote hub repositories

=head1 VERSION

0.1.0_19 (2014-10-08)

=head1 SYNOPSIS

  bifhub COMMAND [...]

=head1 DESCRIPTION

B<Bifhub> is a command-line tool for managing hosted bif hubs. It
provides an interface to providers such as L<bifhub.com>.

Bifhub commands form a superset of the L<bif> command set, so anything
you can do with L<bif> you can do with bifhub. The distinction exists
in order to keep L<bif> and its documentation as small as possible and
focused only on the activities that the majority of L<bif> users will
need.

=head2 Global Options, Command Structure & Interaction

Global options, the structure of the commands, and the command
input/output interaction are the same for bifhub as they are for
L<bif>.

Reference documents however for the extra bifhub commands have titles
like I<bifhub-command-name>.

=head2 Quickstart


If you want to create a new hub and already know the provider's plan &
host(s) you wish to use, you can get up and running with the following
command inside an initialized repository:

    bifhub signup --create hub.name bifhub.com:plan host

This is equivalent to the following:

    bifhub pull provider bifhub.com
    bifhub new hub hub.name
    bifhub signup hub.name plan
    bifhub push hub hub.name host

=head1 TUTORIAL

The first time a C<bifhub> (or a C<bif>) command is run you will be
prompted to create your user identity. Apart from your name and email
address, an SSH public key is required which will identify you to the
provider as all communication takes place via ssh.

=head2 Initialisation

The first action for working with remote bif hubs is to create a
management repository locally, using the C<bifhub init> command:

=for bifcode #!sh

    bifhub init my.org

The first argument to the C<init> command is the name of your hub.  The
name is representative of your project organisation, and should be
globally unique. We generally recommend to use something similar to a
web url.

=head2 Importing a providers plans and locations

The second step is to register a hub provider, in order to see their
hosts and/or availabe plans.

=for bifcode #!sh

    bifhub pull provider bifhub.com

Listing the offers (plans) and locations (hosts) is possible with the
appropriate C<list> command:

=for bifcode #!sh

    bifhub list hosts

    bifhub list plans

=head2 Signing up for a plan

=for bifcode #!sh

    bifhub signup my.org bifhub.com:plan2

This will do a check with the provider to ensure that the name has not
been already taken. If successful you should be able to see the
invoice:

=for bifcode #!sh

    bifhub list invoices

=head2 Pushing a hub to remote hosts

The hub does not go live until you push it up to a particular host.

=for bifcode #!sh

    bifhub push hub my.org HOSTS...

=head2 Team communication

After a push your hub will be available on the designated hosts, and
you can inform your team how to register their L<bif> repositories with
the hub:

    Hi team,

    Our collaboration hub has been created at the following location:

        your.org@zrh.bifhub.com
    
    To access the hub send us your identity from a local bif
    repository:

=for bifcode #!sh

        bif init
        bif push identity 1 your.org@zrh.bifhub.com

    Once we have enabled the permissions you can register the hub:

=for bifcode #!sh

        bif pull hub your.org@zrh.bifhub.com

    And then import the "devel" project to work on straight away.
        
=for bifcode #!sh

        bif pull project devel

        # bif new issue/task etc...

    Don't forget to sync regularly.

=for bifcode #!sh

        bif sync

    Thanks,
    PM

=head2 Synchronising updates

You may want to change your hub name, or the provider may change their
plans, or add to their list of hosts, and so on.  The C<sync> command
is used to exchange these updates.

=for bifcode #!sh

    bifhub sync

=head2 Managing the hub

You can at any time confirm the hub and its status:

=for bifcode #!sh

    bifhub list hubs

    bifhub show hub ID

At some point in the future there will be actions that a hub manager
can take, such as allowing access, defining roles & permissions, paying
invoices and so on.


=head1 FILES

=over

=item F<.bifhub/config>

Per-repository configuration file.

=item F<.bifhub/db.sqlite3>

Per-repository SQLite database.

=item F<$HOME/.bifu/config>

User configuration file.

=back

=head1 SEE ALSO

L<bif>(1)

=head1 AUTHOR

Mark Lawrence E<lt>nomad@null.netE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright 2014 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 3 of the License, or (at your
option) any later version.

