1. Getting started¶
This chapter covers getting started with Socorro using Docker for a local development environment.
If you’re interested in running Socorro in a server environment, then check out Deploying Socorro.
Install docker-compose. You need 1.10 or higher.
It helps to add an alias to your shell:
because it’s way easier to type “dc” and I do it a lot.
Install make using either your system’s package manager (Linux) or homebrew (OSX).
FIXME(willkg): Windows instructions?
From the root of this repository, run:
$ make dockerbuild
That will build the containers required for development: test, processor, and webapp.
Then you need to set up Postgres and Elasticssearch. To do that, run:
$ make dockersetup
This is a work in progress, isn’t idempotent, and is fussy about the state of things.
Pull requests welcome!
At that point, you should have a functional Socorro development environment.
All configuration is done with ENV files located in
Each service uses
docker_common.env and then a service-specific ENV file.
This holds secrets and environment-specific configuration required to get services to work in a docker environment for local development.
This should NOT be used for server environments.
- This holds configuration specific to running the tests. It has some configuration value overrides because the tests are “interesting”.
These configuration files hold behavioral configuration for these two things that work across ALL environments–local development and servers.
For example, if you want to add a new destination crash store to the system, you’d add it to
In this way, we have behavioral configuration versioned alongside code changes and we can more easily push and revert changes.
1.3. General architecture¶
Arrows direction represents the flow of interesting information (crashes, authentication assertions, cached values), not trivia like acks.
1.3.1. Top-level folders¶
If you clone our git repository, you will find the following folders. Here is what each of them contains:
|docker/||Docker environment related scripts, configuration, and other bits.|
|docs/||Documentation of the Socorro project (the one you are reading right now).|
|scripts/||Scripts for launching the different parts of the Socorro application.|
|socorro/||Core code of the Socorro project.|
|sql/||SQL scripts related to our PostgreSQL database. Contains schemas and update queries.|
|tools/||External tools used by Socorro.|
|webapp-django/||Front-end Django application (also called UI). See Webapp (crash-stats analysis app).|
1.3.2. Socorro submodules¶
The core code module of Socorro, called
socorro, contains a lot of code.
Here are descriptions of every submodule in there:
|cron||All cron jobs running around Socorro.|
|database||PostgreSQL related code.|
|external||Here are APIs related to external resources like databases.|
|unittest||All our unit tests are here.|
|webapi||Contains a few tools used by web-based services.|