How to set up a development environment

This guide includes instructions for Linux / macOS and Windows.


You need the following programs installed before proceeding (on all operating systems).

How to use Docker

No matter what operating system you use, you need Docker. Docker is a tool to run applications inside what are known as “containers”. Containers are similar to lightweight virtual machines (VMs). They make it easier to develop, test, and deploy a web application. Fedora Happiness Packets uses Docker for local development and to deploy to the production website.

The project comes with a Dockerfile. A Dockerfile is the instructions for a container build tool (like Docker) to build a container. Look at the Fedora Happiness Packets Dockerfile for an example.

How to install Docker

Install Docker as described in the installation docs. You also need to install Docker Compose. Docker Compose is used to run multiple containers side-by-side. While developing Fedora Happiness Packets, there are a few different services that run in multiple containers, like the Django web app, the Postgres database, and more.

See below for platform specific installation guidelines:

Run initial set-up

This section explains how to get started developing for the first time.

Fork and clone

First, you need to fork the Fedora Happiness Packets repo on to your Pagure account. Then, clone your fork to your workstation using git. For extra help, see the Pagure first steps help page. Once you clone your fork, you need to run a script to generate authentication tokens (more on this later).

git clone "ssh://<username>/fedora-commops/fedora-happiness-packets.git"
cd fedora-happiness-packets

Although Docker runs this script during container build-time, please generate a local copy first. This way, new client keys are not being generated each time the container is rebuilt. This avoids rate-limiting by the authentication service.

Add FAS account login info

Next, you need to configure Fedora Happiness Packets with your Fedora Account System (FAS) username and password. This is used to authenticate with Fedora APIs for username search. Copy the example file fas-admin-details.json.example as a new file named fas-admin-details.json. Add your username and password into the quotes.

Create a project config file

Next, create a configuration file to add admin users to Fedora Happiness Packets. Like before, copy config.yml.example to a new file named config.yml. Add your name and email address for ADMINS. For superuser privileges, add your FAS username to the list.

How to test sending emails

In the development environment, sending emails is tested in one of two ways:

  • Using console
  • Using third-party mail provider (e.g. Gmail

Using console

The default setup is to send emails on the console. The full content of emails will appear in the docker-compose console output (explained below). To see this in action, no changes are needed.

Using Gmail

Sending real, actual emails can be tested with a third-party mail provider, like Gmail. There are other mail services you can use, but this guide explains using Gmail. To test this functionality:

  1. In settings/, un-comment the setting for Configurations to test sending emails using Gmail SMTP. Comment out the setting under Configurations for sending email on console. In docker-compose.yml, un-comment the ports setting in celery service.
  2. Enable less secure apps in the Gmail account which you want to use as the host email. (It is strongly recommended to not allow less secure apps in your primary Gmail account. A separate account for testing is recommended with this setting enabled.)
  3. Replace <HOST@EMAIL.COM> and <HOST_EMAIL_PASSWORD> with the email address of the above account and its password.

Start Fedora Happiness Packets with Docker Compose

Now you are ready to start Fedora Happiness Packets! You will use Docker Compose to start all the containers used at the same time (like Redis, Celery, and others). Run this command to start up the project:

docker-compose up

Once it finishes starting up, open localhost:8000 in your browser You should see the Fedora Happiness Packets home page.

Thanks to PR #235 from @ShraddhaAg, changes to Django code, HTML templates, and CSS/JavaScript are automatically reloaded while docker-compose is running. You should not need to rebuild the containers every time you make a change. However, sometimes you will need to rebuild the containers (e.g. adding a new dependency). This can be done with the following command:

docker-compose up --build

Run integration tests

Integration tests are tests that ensure an application works fully from beginning to end. Fedora Happiness Packets is not fully tested, but there are some integration tests. To run integration tests, you need to enter the container while it is running and run the test suite. Open a new window and run this command to open a shell prompt inside the Django web app container:

docker-compose exec web bash

Once inside the container, run this command:

docker-compose exec web ./ test -v 2 -p integration_test*.py --settings=happinesspackets.settings.tsting

Test fedora-messaging integration

To test if messages are being sent to the RabbitMQ broker, open a new terminal while docker-compose is running. Run the following commands:

docker-compose exec web bash
fedora-messaging consume --callback=fedora_messaging.example:printer

The messages sent to the RabbitMQ broker, when a sender confirms sending a happiness packet, will be printed in this terminal.

Alternatives to Docker

There are other ways to run Fedora Happiness Packets without containers or Docker. However, this is discouraged as current maintainers use containers to test changes and deploy Fedora Happiness Packets to production. If you choose to not use Docker and set up everything manually, you may run into unexpected issues. Project maintainers cannot easily help you if you choose this route (and may not be able to help you)! Therefore, please consider very carefully if you wish to run everything locally without containers.


Windows: error ERROR: unsatisfiable constraints

On Windows, you might get the above error when running docker-compose. This can be resolved by following these steps:

  1. Open Docker settings.
  2. Click on Network.
  3. Look for “DNS Server” section.
  4. It is set to Automatic by default. Change it to Fixed.
  5. The IP address should now be editable. Try changing it to
  6. Save settings.
  7. Restart Docker.