-
Notifications
You must be signed in to change notification settings - Fork 90
setup
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.
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.
- Git to fetch the projects repositories from Github.
- cURL - Windows users can get it here
- A CouchApp deployment tool, for example:
- CouchApp: the original python command line tool. Instructions are provided to install it on Linux, Mac OS X, Windows (there is a simple installer for Windows)
- Erica: the new generation of CouchApp deployment. Available only on Linux for the moment.
- 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.
- The build-couchdb project also provides an easy way to build couchdb from its sources.
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.
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 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
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.
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 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.
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 thereader
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.
Before CouchDB 1.2, user creation requires sending a salted hashed password. You can follow this procedure to create your users.
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.
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 clickUpdate
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.
If your host is Cloudant, you can set the database to be readable to everyone from the Permissions tab of your dashboard.
You need ACRA v4.5.x to send reports to Acralyzer. Get it here: https://oss.sonatype.org/content/groups/public/ch/acra/acra/4.5.0/acra-4.5.0.zip (also available in 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 = org.acra.sender.HttpSender.Type.JSON,
httpMethod = org.acra.sender.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);
}
...
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.