Skip to content
KevinGaudin edited this page Feb 23, 2013 · 64 revisions

Installing Acralyzer

Components

Acralyzer is built with 2 components:

  • a storage database (acra-storage)
  • an analysis web application (Acralyzer)

These 2 components are GPLv3 licensed open source CouchApp projects.

CouchApps are web applications made of HTML/Javascript files and served directly by a CouchDB.

This allows you to deploy Acralyzer with simple command line instructions to a single CouchDB instance.

CouchDB is all you need to have Acralyzer running. No server-side PHP/Java/Ruby/Python is involved.

CouchDB admin with Futon

Futon is the CouchDB admin application. It is usually available at the URL http://your.couchdb.instance/_utils.

Some hosting services such as Cloudant host Futon on a different URL. For Cloudant, you have to connect to the Cloudant dashboard and select a database. An option to

Requirements

  • Git to fetch the projects repositories from Github.
  • cURL - Windows users can get it here
  • A CouchApp deployment tool, for example:
  • A CouchDB instance:

Get acra-storage and acralyzer projects from Github

Create a directory on your filesystem where you want to store these 2 projects. In this directory, execute the commands:

$ git clone http://github.com/ACRA/acra-storage.git
$ git clone http://github.com/ACRA/acralyzer.git

This creates two directories acra-storage and acralyzer with each project's contents.

Turn off Admin Party

You can read a more detailed description of the security model of CouchDB adapted to Acralyzer.

Unless you don't care about your whole database being writable/destroyable by anyone, you should turn the 'Admin Party' mode off by creating an admin user.

After this is done, only your admin users can create/delete database and update application design documents.

Deploy acra-storage

Deploy the first couchapp using the following command lines:

$ cd acra-storage
$ couchapp push http://[login]:[password]@[your.couchdb.host]:[port]/acra-[yourappname]

Replace all [parameters] with the correct values for your situation, for example, let's imagine I work for the company ACME and we develop an Android application called GreatApp. We have subscribed to an IrisCouch hosting with a hostname acme.iriscouch.com. The couchapp push command would look like:

$ couchapp push http://kevingaudin:[email protected]/acra-greatapp

Configure and deploy acralyzer

Edit the file acralyzer/_attachments/script/config.js and update the variable acralyzerConfig.defaultApp with the name of your app. With the previous example, you have to change:

    // Update this variable with the name of your app:
    acralyzerConfig.defaultApp = "storage";

into:

    // Update this variable with the name of your app:
    acralyzerConfig.defaultApp = "greatapp";

Deploy the second couchapp using the following command lines:

$ cd ../acralyzer
$ couchapp push http://[login]:[password]@[your.couchdb.host]:[port]/acralyzer

Replace all the [parameters] with the values for your couchdb instance. With the same example as above, it looks like:

$ couchapp push http://kevingaudin:[email protected]/acralyzer

As a result, a message should be displayed guiding you to the home page of your acralyzer instance.

2013-02-05 23:44:15 [INFO] Visit your CouchApp here:
http://acme.iriscouch.com/acralyzer/_design/acralyzer/index.html

You can already visit this link and see an empty dashboard layout.

Create a 'reporter' user

The acra-storage database is configured to let only identified users insert data (reports). You need to create such a new user in your couchdb database and give him the role 'reporter'.

CouchDB 1.2 and later (including IrisCouch)

Use curl to create a new user:

$ curl -X PUT -u [adminuser]:[adminpassword] http://[your.couchdb.host]:[port]/_users/org.couchdb.user:[newuserid] -d '{"name":"[newusername]", "password":"[newuserpassword]", "roles":["reporter", "reader"], "type":"user"}' -H "Content-Type: application/json"

Prior to CouchDB 1.2 (including Cloudant at the time of this writing)

Before CouchDB 1.2, user creation requires sending a salted hashed password. You can follow this procedure to create your users.

Optional: create a 'reader' user

If you want to give access to Acralyzer to people who you don't want to give admin access to your couchdb, use the same method to create a second user which will receive the "reader" role.

If your host is Cloudant, you can grant permissions to your users by following these instructions.

NOT Optional: Secure access to your storage database

You can set who is allowed to read the content of one database in Futon:

  • From your Futon root, select your acra-[yourApp] database

  • Click on Security

  • set ["reader"] in the Members Roles input and click Update

    The acralyzer database can (and should) stay readable to anyone. This will let you access to the app and login without having first to login in Futon. All your sensible data is stored in the acra-storage instance and is readable only to admins or users with the "reader" role.

Configure your application to send reports to your acra-storage

You need ACRA v4.5.x to send reports to Acralyzer. There is no official release for this version for the moment, but you can get a SNAPSHOT build from the Maven central repository.

In your Android Application class, update your ACRA configuration to look like the following:

@ReportsCrashes(
        formKey = "",
        formUri = "https://[your.couchdb.host]/acra-[yourappname]/_design/acra-storage/_update/report",
        reportType = Type.JSON,
        httpMethod = Method.PUT,
        formUriBasicAuthLogin="[reporteruser]",
        formUriBasicAuthPassword="[reporterpassword]",
        // Your usual ACRA configuration
        mode = ReportingInteractionMode.TOAST,
        resToastText = R.string.crash_toast_text,
        ...
        )
public class [YourApplication] extends Application {
    ...

Handling more Android apps

You can create several acra-[yourappname] databases to handle reports from different apps.

All you have to do is couchapp push the acra-storage instance and setup its users.

Acralyzer discovers automatically all acra-* databases as application crashes reports repositories.

Clone this wiki locally