NAME

TaskPipe::Tool::Command_Setup - the TaskPipe setup command

PURPOSE

Setup is intended to be run once immediately after running package install (ie after installing the modules with cpan, cpanm or manually with make). Setup creates the directories TaskPipe will use to store projects, and deploys the global configuration files.

DESCRIPTION

You need to specify a value for root_dir at a minimum, e.g.:

    taskpipe setup --root_dir=/home/myusername/taskpipe

Subdirectories can also be specified on the command line, but will take defaults otherwise. (See options section below for default values)

You can also use setup to regenerate global directories and/or default global config files if you want to change overall directory structure or reset the global config files to factory defaults. Use with caution. Setup will not overwrite files or directories that already exist - it will ignore them. So you should delete the directories/files you want to regenerate prior to running setup.

GENERAL TASKPIPE SETUP INSTRUCTIONS

You may be looking at this help because you want to know how to setup TaskPipe in general. In fact the command taskpipe setup does not completely setup TaskPipe on your system (sorry!) mainly because TaskPipe doesn't immediately know how to connect to your database.

taskpipe setup installs the skeleton directory structure and the global config file. You should run taskpipe setup immediately after install, because taskpipe needs to find the global config file to be able to do anything further.

A suggested workflow to achieve a full setup and working projects is as follows:

1. Install TaskPipe

Do this using the cpan shell, cpanp, cpanm etc. or manually using make:

    perl Makefile.PL
    make
    make test
    make install

If you are reading this using the taskpipe help setup command, you have already successfully completed this step.

2. Run setup

    taskpipe setup --root_dir=~/taskpipe

The /taskpipe subdirectory inside your home directory is the suggested location to install TaskPipe and these docs will tend to assume this is your install location. However, any location where you have full read/write permissions is good.

Note that TaskPipe installs a hidden file .taskpipe in your home directory which will store the path to your TaskPipe install. You need to make sure TaskPipe can create this file and it remains in place and readable.

Once you have run setup, you should find the following directory structure is created

    /taskpipe
        /global
            /conf
                global.conf
            /lib
        /projects

3. Set up the global database

To do this

• Create the database that you are going to use for TaskPipe global tables. E.g. in MySQL

      CREATE DATABASE taskpipe_global;

• Edit the global config file to tell TaskPipe which database to use.

      nano ~/taskpipe/global/conf/global.conf

  Look for the section TaskPipe::SchemaManager::Settings_Global and fill in host, name etc. for your database. Make sure the database user account you specified has full privileges to your TaskPipe global database.

• Run deploy tables:

      taskpipe deploy tables --scope=global

  More comprehensive information on this step can be found in the help for deploy tables.

• Generate global database schema files. TaskPipe uses the DBIx::Class ORM, and schema files need creating over each database being used. To do this, you should just be able to type:

      taskpipe generate schema --scope=global

  Schema files will be generated into the global lib dir (normally /global/lib).

  More comprehensive information on this step can be found in the help for generate schema

4. Create your project

To do this for a new project called myproject:

• Edit the global config file and change project to myproject in the section TaskPipe::PathSettings::Global. This basically means you have set myproject as the default project, so that you don't need to type --project=myproject each time you execute a project-related TaskPipe command at the terminal.

• Deploy project files:

      taskpipe deploy files

  See the help for deploy files for more comprehensive information on this step.

• Create a database to use for this project. E.g. in MySQL:

      CREATE DATABASE myproject;

  Make sure your database user account has full privileges to this database. E.g. in MySQL

      GRANT ALL PRIVILEGES ON myproject.* TO 'taskpipe_user'@'localhost';

• Edit the project config file and change the database connection information (host, name, ...) to match the project database. (Look for the section TaskPipe::SchemaManager::Settings_Project in your project config file (usually found in the /projects/myproject/conf/project.yml file.

• Deploy the project cache tables:

      taskpipe deploy tables

  See the help for deploy tables for more comprehensive information on this step.

• Create the project itself. A project consists of several tasks, a plan of how to execute those tasks and some database tables to store gathered data. This is the meat and potatoes of TaskPipe, and here it is up to you to be creative. See the general instructions by reading the manpage for the TaskPipe module or typing

      taskpipe help taskpipe

  on the command line for more information on how to create projects.

• Run generate schema over your project to create the project schema files

      taskpipe generate schema

  See the help for generate schema for more information.

5. Run your plan

Run your plan and gather your data:

    taskpipe run plan

See the help for run plan for more information on this step.

OPTIONS

root_dir

The base directory where all TaskPipe files and subdirectories should be installed. This parameter is required.

AUTHOR

Tom Gracey <tomgracey@gmail.com>

COPYRIGHT AND LICENSE

Copyright (c) Tom Gracey 2018

TaskPipe is free software, licensed under

    The GNU Public License Version 3