A system to manage Pulse: creates users and handle overgrowing queues. More information on the wiki.

• RabbitMQ (tested on 3.3.0)
• Python 2.7
• pip (to install external dependencies)
• PostgreSQL (for production; testing environments can use sqlite)

Using a virtualenv is highly recommended. One possible installation would be

• Clone the repository and cd into it.

• Create and activate a virtualenv:

    virtualenv venv
    source venv/bin/activate
  

Within the chosen environment, install and configure PulseGuardian:

• Install the requirements:

    pip install -r requirements.txt
  

• Install the package. This will ensure you have access to the pulseguardian package from anywhere in your virtualenv.

    python setup.py develop
  

Because Persona requires an https connection, if you are running the development server without the FAKE_ACCOUNT option (see below), you will also need the pyOpenSSL package:

pip install pyOpenSSL

You will also need a RabbitMQ instance running somewhere. Docker provides a lightweight and isolated solution. See the docker installation docs for your system.

To create a Pulse Docker image, run this from within the test directory (which contains the necessary Dockerfile):

docker build -t="pulse:testing" test

When that finishes building, you can run a RabbitMQ instance in a Docker container with

docker run -d -p 5672:5672 -p 15672:15672 --name pulse pulse:testing

This will run RabbitMQ in a container in the background. It will also forward the AMQP and management API ports, 5672 and 15672, respectively, from the container to your local host.

To stop the container, run

docker stop pulse

You can remove the container with

docker rm pulse

And you can remove the images with

docker rmi pulse:testing
docker rmi ubuntu:14.04

You can also use either a local RabbitMQ server or a VM. See the mozillapulse HACKING.md file for instructions on setting up both of these.

Finally, you need your environment set up correctly. If you are running RabbitMQ in the Docker configuration described above, the defaults should be mostly fine. You will need to set FLASK_SECRET_KEY and probably DATABASE_URL. To use a random secret key and a local sqlite database named pulseguardian.db, run the following from within the root PulseGuardian source directory:

export FLASK_SECRET_KEY=`python gen_secret_key.py`
export DATABASE_URL=sqlite:///`pwd`/db

See the complete listing of options in pulseguardian/config.py.

TODO: Each of these options should be documented in the source.

Make sure rabbitmq-server is running, your environment variables are configured properly, and that you're inside the source directory (pulseguardian) before you run the following commands.

Note that tests are run on Travis CI. Before submitting a patch, it is highly recommended that you get a Travis CI account and activate it on a GitHub fork of the pulseguardian repo. That way the reviewer can quickly verify that all tests still pass with your changes.

• Initialize the db with: python pulseguardian/dbinit.py. WARNING: This removes any existing data the app might have previously stored in the database.
• Set the environment variable FAKE_ACCOUNT to a valid email address.
• Optional: Generate some dummy data (dummy user account, admin account): python pulseguardian/dbinit.py --dummy
• Run the Pulse Guardian daemon with: python pulseguardian/guardian.py
• Run the web app (for development) with: python pulseguardian/web.py
• For production, the web app can be run with gunicorn and such.

The FAKE_ACCOUNT variable will make development easier. This feature will disable HTTPS and bypass Persona for testing. It will also create the given user, if necessary, and log in automatically.

PulseGuardian uses docker to run its test suite. Please follow the docker installation docs on how to install it in your system.

With docker installed and configured appropriately, run

python test/runtests.py

The required docker image will be built and container started before the tests are run.

If you are using OS X with docker-machine, don't forget to set the environment variables before running the tests via

eval "$(docker-machine env <machine>)"

where <machine> is your docker-machine name, quite possibly default.

The docker container forwards ports 5672 and 15672. Please be sure that they are available.

Since PulseGuardian is configured via environment variables, you must ensure that you have a clean environment before running the tests, i.e., no PulseGuardian environment variables set. (FIXME: set up a full test environment from within runtests.py rather than relying on defaults.)

Some Linux-specific notes:

• The docker daemon must always run as the root user, but you need to be able to run docker client commands without sudo. To achieve that you can:

• Add the docker group if it doesn't already exist: sudo groupadd docker

• Add the connected user "${USER}" to the docker group. Change the user name to match your preferred user: sudo gpasswd -a ${USER} docker

• Restart the Docker daemon: sudo service docker restart

• You need to log out and log back in again if you added the currently logged-in user.

If you prefer, you can run the tests against a local RabbitMQ installation. For that you can run: python test/runtests.py --use-local.

WARNING: If you use your local RabbitMQ instance the tests will mess with it (wiping out existing queues, possibly deleting users) so make sure you don't run the tests on a production instance.

PulseGuardian uses Alembic for database migrations. SQLite doesn't support all the SQL commands required for migrations, so you may want to use PostgreSQL even in your development environment, at least if you are testing migrations.

Because PulseGuardian is designed to run on Heroku, which doesn't support locally modified files, the Alembic configuration file, alembic.ini, must be used for all installations, including for local development. The database URL, sqlalchemy.url, is not used; instead, migration/env.py is set to use the DATABASE_URL environment variable, as the rest of PulseGuardian does.

To migrate the database,

• Install the alembic package (if you haven't yet): pip install -r requirements.txt
• Run alembic upgrade head