Skip to content
Permalink
Browse files
Updates to setup advice
  • Loading branch information
Gary Martin committed Sep 23, 2020
1 parent ac3d187 commit d5f0a61e2836ce8b1c8aa6b7bce134264ae8c003
Showing 1 changed file with 65 additions and 47 deletions.
112 README.md
@@ -1,61 +1,67 @@
# New Bloodhound

## Requirements
## Getting the Bloodhound Code:

### Python
There is a reasonable chance that you are reading these instructions from a
copy of the source code that you have already placed on the computer that you
wish to install on. If this is the case you can skip on to the next section.

Bloodhound core is currently written in Python3. It should be possible to
install and run the core successfully with Python 3.6 or newer. You may
find that versions from Python 3.4 work but this is not currently tested
and it is possible that Python features from newer versions may sneak in.
While in early development, the alternatives for getting the code include
checking out from [Subversion] with the following command:

If you do not already have an appropriate version of Python installed, you
may wish to follow instructions for your platform here:
```
svn checkout https://svn.apache.org/repos/asf/bloodhound/branches/bh_core_experimental/ bloodhound
```

https://docs.python-guide.org/starting/installation/
or cloning with [Git] from the [Apache Bloodhound Github mirror] - the command
below should also check out the appropriate branch:

### Pipenv
```
git clone --branch bh_core_experimental https://github.com/apache/bloodhound.git
```

Pipenv is used for looking after Python package dependencies and virtual
environment management.
With the commands as specified, both will place the code in the `bloodhound`
directory.

If you already have the `pip` program installed already, installation of
pipenv can be as simple as
[Subversion]: https://subversion.apache.org/
[Git]: https://git-scm.com/
[Apache Bloodhound mirror]: https://github.com/apache/bloodhound
[Github]: https://github.com/

```
pip install --user pipenv
```
## Installing Python and Pipenv

For more information on installing and usage of pipenv, see
https://docs.pipenv.org/.
Bloodhound core is currently written in [Python 3] and uses [Pipenv] for
looking after the python based dependencies.

Once pipenv is installed, the final bit of setup ahead of installing the
rest of the project dependencies is to ensure that you have picked out the
appropriate version of Python for your environment. For the same directory
as the `Pipfile` for the project, you should run:
It should be possible to install and run the core successfully with Python 3.6
or newer. You may find that versions from Python 3.4 work but this is not
currently tested and it is possible that Python features from newer versions
may sneak in.

```
pipenv --python 3
```
The guide at <https://docs.python-guide.org/> gives good instructions for
installing Python on [Linux][Python on Linux], [MacOS][Python on MacOS] and
[Windows][Python on Windows].

If you have multiple versions of Python 3 installed, you may need to be
more specific about the version.
Further information about pipenv is available at <https://docs.pipenv.org/>.

### Pipfile Specified Requirements
[Python 3]: https://docs.python.org/3/
[Pipenv]: https://pipenv.readthedocs.io/en/latest/
[Python on Linux]: https://docs.python-guide.org/starting/install3/linux/#install3-linux
[Python on MacOS]: https://docs.python-guide.org/starting/install3/osx/#install3-osx
[Python on Windows]: https://docs.python-guide.org/starting/install3/win/#install3-windows

With pipenv installed and the Python version selected, the rest of the
Python based requrements can be installed with the following command from
the same director as the `Pipfile` for the project:
## Preparing the Python environment

```
pipenv install
```
It should now be possible to use pipenv to install the rest of the project
dependencies and bloodhound itself. Note that the exactly required command may
depend on details like whether you have multiple versions of python available
but for most cases, the following should work. If in doubt, just be more
specific about the python version that you intend to use.

Additionally, to run tests described later, you should install the
development dependencies:
For the same directory as the `Pipfile` for the project run:

```
pipenv install --dev
pipenv --python 3 install
```

## Setup
@@ -104,27 +110,28 @@ These paths are subject to change.
Unit tests are currently being written with the standard unittest framework.
This may be replaced with pytest.

The tests may be run with the following command:
Running the tests require a little extra setup:

```
pipenv run python manage.py test
pipenv install --dev
```

Fixtures for tests when required can be generated with:
after which the tests may be run with the following command:

```
pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml
pipenv run python manage.py test
```

## Integration Tests

Selenium tests currently require that Firefox is installed and `geckodriver` is
also on the path. One way to do this is (example for 64bit linux distributions):

The [Selenium] tests currently require that Firefox is installed and
[geckodriver] is also on the path. If you
```
BIN_LOCATION="$HOME/.local/bin"
PLATFORM_EXT="linux64.tar.gz"
TMP_DIR=/tmp
BIN_LOCATION="$HOME/.local/bin"
TMP_DIR=/tmp/geckodriver_download
mkdir -p "$BIN_LOCATION" "$TMP_DIR"
LATEST=$(wget -O - https://github.com/mozilla/geckodriver/releases/latest 2>&1 | awk 'match($0, /geckodriver-(v.*)-'"$PLATFORM_EXT"'/, a) {print a[1]; exit}')
wget -N -P "$TMP_DIR" "https://github.com/mozilla/geckodriver/releases/download/$LATEST/geckodriver-$LATEST-$PLATFORM_EXT"
tar -x geckodriver -zf "$TMP_DIR/geckodriver-$LATEST-$PLATFORM_EXT" -O > "$BIN_LOCATION"/geckodriver
@@ -140,3 +147,14 @@ pipenv run python functional_tests.py

There are currently not many tests - those that are there are in place to test
the setup above and assume that there will be useful tests in due course.

[Selenium]: https://selenium.dev/
[geckodriver]: https://firefox-source-docs.mozilla.org/testing/geckodriver/

## Development notes:

Fixtures for tests when required can be generated with:

```
pipenv run python manage.py dumpdata trackers --format=yaml --indent=2 > trackers/fixtures/[fixture-name].yaml
```

0 comments on commit d5f0a61

Please sign in to comment.