--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/INSTALL.pod Sat Dec 31 20:33:24 2016 +0100
@@ -0,0 +1,190 @@
+=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