=head1 INSTALLATION

=head2 Compile breakpad and stackwalker from Socorro

Install system packages:

  apt install build-essential libjsoncpp-dev libcurl4-openssl-dev git wget python pkg-config

Get and build breakpad:

L<https://chromium.googlesource.com/breakpad/breakpad>

Get and build the json minidump-stackwalk from soccoro:

L<https://github.com/mozilla/socorro/tree/master/minidump-stackwalk/>

Full compilation instructions:

  mkdir breakpad-stackwalker && cd breakpad-stackwalker

  git clone https://chromium.googlesource.com/chromium/tools/depot_tools.git

  export PATH="$PWD/depot_tools:$PATH"

  fetch breakpad

  mkdir obj-breakpad && cd obj-breakpad

  ../src/configure

  make

  cd ../

  mkdir minidump-stackwalk && cd minidump-stackwalk

  wget https://github.com/mozilla/socorro/raw/master/minidump-stackwalk/{Makefile,stackwalker.cc,http_symbol_supplier.cc,http_symbol_supplier.h,common.h}

  make stackwalker \

    BREAKPAD_SRCDIR=../src/src \

    BREAKPAD_LIBS="../obj-breakpad/src/libbreakpad.a ../obj-breakpad/src/third_party/libdisasm/libdisasm.a" \

    JSON_INCLUDEDIR=/usr/include/jsoncpp \

    stackwalker_OBJS="/usr/lib/libjsoncpp.so"

Note: the paths above are for the system-installed libjsoncpp on debian. Get

jsoncpp from socorro repository, or adjust the paths for you system if you

use another distribution.

=head2 Web Interface installation

=head3 Install system packages (Debian)

Install direct dependencies:

  apt install libjs-jquery libuuid-perl libdata-page-perl libdatetime-format-pg-perl \

      libsearch-queryparser-perl libdbi-perl libdbd-pg-perl libpq-dev

and indirect dependencies:

  apt install cpanminus libextutils-installpaths-perl libfile-sharedir-perl libfile-sharedir-install-perl \

      libextutils-helpers-perl libmodule-build-cleaninstall-perl \

      libmojolicious-plugin-i18n-perl libdata-dump-perl

If your system is recent enough (Debian jessie is too old), also install:

  apt install libmojolicious-perl libminion-perl libmojo-pg-perl

Or use carton (Bundler for perl), if you prefer to bundle dependencies:

  apt install carton uuid-dev

=head3 Install the web interface

  tar -xf CrashTest-$VERSION.tar.gz

  cd CrashTest-$VERSION

use cpanm to install missing perl dependencies:

  cpanm Minion@4.0 .

or carton to vendorize half of CPAN:

  carton install

=head3 Database

Install PostgreSQL (PostgreSQL E<gt>= 9.4 is required):

  apt install postgresql postgresql-contrib postgresql-9.4-debversion

Create the user and database:

  su postgres

  psql

  CREATE USER crashtest LOGIN;

  CREATE DATABASE crashtest OWNER crashtest;

Add PostgreSQL extensions to the database:

  \c crashtest

  CREATE EXTENSION pg_trgm;

  CREATE EXTENSION debversion;

debversion is not required, but is really useful to sort and filter on product versions

=head2 Configuration

Copy the example crash_test.conf from F<extras/> and edit:

  cp extras/crash_test.conf .

  vim crash_test.conf

It's a perl file, so you can check the syntax with:

  perl -c crash_test.conf

Some things to change:

=over

=item Database

Adjust your database connection string in C<Processor/JobQueue/Backend/Minion> and C<Storage/Sql/db>.

The database can be shared by the JobQueue and Storage.

=item stackwalker path

If you did not install stackwalker in your $PATH, adjust C<Processor/CrashProcessor/Breakpad/JSONStackwalker>

=item Breakpad symbols directories

Set the paths where you store you breakpad symbols in C<Processor/CrashProcessor/Breakpad/SymbolsPath>.

SECURITY WARNING: this will be shell-expanded using C<system()>, don't use wildcards if you do not trust

the users that have write permissions on these directories.

=item Storage directory

Adjust C<Storage/File> or comment the section if you don't want to store the raw minidumps.

Processed crashs are also stored in the database.

=item Web links

You can link to your source code browser (this require post-processing of the symbol files),

see C<WebInterface/ScmLinks>.

It's a C<Mojo::Template> with the 3 variables C<$scmpath>, C<$rev> and C<$line> defined.

You can also add links to your bugtracker (C<WebInterface/BugTrackerLinks>), but there is no interface

to edit them yet.

=back

=head2 Create database structure

Run:

  CrashTest db create

or with carton:

  carton exec CrashTest db create

If you have installed the debversion PostgreSQL extension, use it:

  psql

  ALTER TABLE products ALTER version TYPE debversion;

=head1 RUNNING

=head2 Manually (for testing)

Start the background workers

  CrashTest minion worker

Start the web interface

  CrashTest daemon

=head2 Production (services)

In the F<extras/> directory, you will find:

=over

=item F<crash_test.production.conf>

A config file with production settings for hypnotoad.

Copy to the same location as F<crash_test.conf>, F</etc/crashtest/> for a system-wide install.

=item F<crashtest.nginx.conf>

Config file for nginx. Usually in F</etc/nginx/sites-enabled/>.

=item F<systemd/*.service>

Systemd services for the workers and the web interface. Usually in F</etc/systemd/system/>.

=back