Skip to content

setup

Jump to bottom Edit New page
KevinGaudin edited this page Apr 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. A View in Futon button is available.

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:
    • You can install one on your own server or your workstation for testing purposes. See http://couchdb.apache.org/#download.
    • The easiest way is to subscribe to a dedicated CouchDB hosting like IrisCouch or Cloudant. Both provide free service for low usage. Cloudant offers a more secured user management but a less recent CouchDB version (fully compatible with Acralyzer though). Because of this security layer, we would recommend using Cloudant as a free hosting service.

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

This does not apply to Cloudant where Admin Party is not activated on fresh instances.

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.

Cloudant hosting - using an API key

Cloudant offers its own security management on top of CouchDB. It is a really interesting system because it overcomes the limitations of the actual CouchDB users/roles management in enabling a specific _writer role dissociated from the _reader role.

From your Cloudant account dashboard, choose your acra-storage database instance and go to the permissions tab.

Click the Generate API key button. This outputs a Key and a password. The Key is actually a generated username and you will use it with its password as your reporter user.

To ensure that this specific user can only write (and not read) in your crash reports database, in the Permissions pane on the left check only the Write permission on the line corresponding to the generated API key.

CouchDB 1.2 and later (including IrisCouch hosting)

Use curl to create a new user:

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

Be aware that there is a security issue with this setup. As you might have noticed, we can't use the reporter role without the reader role with the current native CouchDB security management. This means that if your reporter user credentials were to be leaked (via decompilation) from your APK, a malicious hacker could have access to your full reports database. You can secure your data by [setting up a reverse proxy].

Prior to CouchDB 1.2

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 the 4.5.0RC2 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 = HttpSender.Type.JSON,
        httpMethod = HttpSender.Method.PUT,
        formUriBasicAuthLogin="[reporteruser]",
        formUriBasicAuthPassword="[reporterpassword]",
        // Your usual ACRA configuration
        mode = ReportingInteractionMode.TOAST,
        resToastText = R.string.crash_toast_text,
        ...
        )
public class [YourApplication] extends Application {
    
  @Override
  public final void onCreate() {
    super.onCreate();
    ACRA.init(this);
  }
    ...

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.

Add a custom footer
Add a custom sidebar
Clone this wiki locally