<commit_before>Setting up the development environment
======================================

.. include:: ../includes/docs-branches.txt

Prerequisites
-------------

SecureDrop is a multi-machine design. To make development and testing
easy, we provide a set of virtual environments, each tailored for a
specific type of development task. We use Vagrant, VirtualBox, and
Docker and our Ansible playbooks can provision these environments on
either virtual machines or physical hardware.

Quick start
-----------

The Docker based environment is suitable for developing the web application
and updating the documentation.


Ubuntu or Debian GNU/Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: sh

   sudo apt-get update
   sudo apt-get install -y make git

We recommend using the stable version of Docker CE (Community Edition) which can
be installed via the official documentation links:

* `Docker CE for Ubuntu`_
* `Docker CE for Debian`_

.. _`Docker CE for Ubuntu`: https://docs.docker.com/install/linux/docker-ce/ubuntu/
.. _`Docker CE for Debian`: https://docs.docker.com/install/linux/docker-ce/debian/


Mac OS X
~~~~~~~~

Install Docker_.

.. _Docker: https://store.docker.com/editions/community/docker-ce-desktop-mac


Fork & Clone the repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now you are ready to get your own copy of the source code.
Visit our repository_ fork it and clone it on you local machine:


.. code:: sh

   git clone git@github.com:<your_github_username>/securedrop.git

Using the Docker environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Docker based helpers are intended for rapid development on the
SecureDrop web application and documentation. They use Docker images
that contain all the dependencies required to run the tests, a demo
server etc. The SecureDrop repository is bind mounted into the
container and files modified in the container are also modified in the
repository. This container has no security hardening or monitoring.

To get started, you can try the following:

.. code:: sh

   cd securedrop
   make dev                                    # run development servers
   make test                                   # run tests
   bin/dev-shell bin/run-test tests/functional # functional tests only
   bin/dev-shell bash                          # shell inside the container

SecureDrop consists of two separate web applications (the Source Interface and
the Journalist Interface) that run concurrently. In the development environment
they are configured to detect code changes and automatically reload whenever a
file is saved. They are made available on your host machine by forwarding the
following ports:

* Source Interface: `localhost:8080 <http://localhost:8080>`__
* Journalist Interface: `localhost:8081 <http://localhost:8081>`__

A demo journalist user is created by default when running ``make dev`` and has
the following credentials:

* username: journalist
* password: <PASSWORD>
* TOTP secret: <KEY>

Setting up a multi-machine environment
--------------------------------------

.. note:: You do not need this step if you only plan to work on the
   web application or the documentation.

To get started, you will need to install Vagrant, VirtualBox, Docker, and
Ansible on your development workstation.


Ubuntu or Debian GNU/Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note:: Tested on: Ubuntu 16.04 and Debian GNU/Linux stretch

.. code:: sh
<commit_msg>docs: Clarify setup instructions for TOTP in dev environment<commit_after>Setting up the development environment
======================================

.. include:: ../includes/docs-branches.txt

Prerequisites
-------------

SecureDrop is a multi-machine design. To make development and testing
easy, we provide a set of virtual environments, each tailored for a
specific type of development task. We use Vagrant, VirtualBox, and
Docker and our Ansible playbooks can provision these environments on
either virtual machines or physical hardware.

Quick start
-----------

The Docker based environment is suitable for developing the web application
and updating the documentation.


Ubuntu or Debian GNU/Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: sh

   sudo apt-get update
   sudo apt-get install -y make git

We recommend using the stable version of Docker CE (Community Edition) which can
be installed via the official documentation links:

* `Docker CE for Ubuntu`_
* `Docker CE for Debian`_

.. _`Docker CE for Ubuntu`: https://docs.docker.com/install/linux/docker-ce/ubuntu/
.. _`Docker CE for Debian`: https://docs.docker.com/install/linux/docker-ce/debian/


Mac OS X
~~~~~~~~

Install Docker_.

.. _Docker: https://store.docker.com/editions/community/docker-ce-desktop-mac


Fork & Clone the repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Now you are ready to get your own copy of the source code.
Visit our repository_ fork it and clone it on you local machine:


.. code:: sh

   git clone <EMAIL>:<your_github_username>/securedrop.git

Using the Docker environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The Docker based helpers are intended for rapid development on the
SecureDrop web application and documentation. They use Docker images
that contain all the dependencies required to run the tests, a demo
server etc. The SecureDrop repository is bind mounted into the
container and files modified in the container are also modified in the
repository. This container has no security hardening or monitoring.

To get started, you can try the following:

.. code:: sh

   cd securedrop
   make dev                                    # run development servers
   make test                                   # run tests
   bin/dev-shell bin/run-test tests/functional # functional tests only
   bin/dev-shell bash                          # shell inside the container

SecureDrop consists of two separate web applications (the Source Interface and
the Journalist Interface) that run concurrently. In the development environment
they are configured to detect code changes and automatically reload whenever a
file is saved. They are made available on your host machine by forwarding the
following ports:

* Source Interface: `localhost:8080 <http://localhost:8080>`__
* Journalist Interface: `localhost:8081 <http://localhost:8081>`__

A demo journalist user is created by default when running ``make dev`` and has
the following credentials:

* username: journalist
* password: <PASSWORD>
* TOTP secret: <KEY>

To generate the six digit token you need for logging in, use the TOTP secret in
combination with an authenticator application that implements
`RFC 6238 <https://tools.ietf.org/html/rfc6238>`__, such as
`FreeOTP <https://freeotp.github.io/>`__ (Android and iOS) or
`oathtool <http://www.nongnu.org/oath-toolkit/oathtool.1.html>`__
(command line tool, multiple platforms).

Setting up a multi-machine environment
--------------------------------------

.. note:: You do not need this step if you only plan to work on the
   web application or the documentation.

To get started, you will need to install Vagrant, VirtualBox, Docker, and
Ansible on your development workstation.


Ubuntu or Debian GNU/Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note:: Tested on: Ubuntu 16.04 and Debian GNU/Linux stretch

.. code:: sh

{'fraction_non_alphanumeric': 0.11758180809761509, 'fraction_numerical': 0.006794231835829174, 'mean_word_length': 3.591343093570974, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 8, 'lorem ipsum': 0, 'www.': 1, 'xml': 0}, 'pii_count': 1, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1198315', 'n_tokens_mistral': 1945, 'n_tokens_neox': 1737, 'n_words': 859}