| commit | 104011c39fc8165a59faf49709fa51b1a7cded9c | [log] [tgz] |
|---|---|---|
| author | Gary Martin <gjm@apache.org> | Tue Sep 22 15:40:30 2020 +0100 |
| committer | Gary Martin <gjm@apache.org> | Wed Sep 23 20:06:12 2020 +0100 |
| tree | 3ed862b4d4aa7bf5ce7142a131f73406f562c314 | |
| parent | d5f0a61e2836ce8b1c8aa6b7bce134264ae8c003 [diff] |
Correct path in README.md; add superuser creation
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.
While in early development, the alternatives for getting the code include checking out from Subversion with the following command:
svn checkout https://svn.apache.org/repos/asf/bloodhound/branches/bh_core_experimental/ bloodhound
or cloning with Git from the [Apache Bloodhound Github mirror] - the command below should also check out the appropriate branch:
git clone --branch bh_core_experimental https://github.com/apache/bloodhound.git
With the commands as specified, both will place the code in the bloodhound directory.
Bloodhound core is currently written in Python 3 and uses Pipenv for looking after the python based dependencies.
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.
The guide at https://docs.python-guide.org/ gives good instructions for installing Python on Linux, MacOS and Windows.
Further information about pipenv is available at https://docs.pipenv.org/.
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.
For the same directory as the Pipfile for the project run:
pipenv --python 3 install
Although it will make the commands more verbose, where a command requires the pipenv environment that has been created, we will use the pipenv run command in preference to requiring that the environment is ‘activated’.
The basic setup steps to get running are:
pipenv run python manage.py makemigrations trackers pipenv run python manage.py migrate
The above will do the basic database setup.
Note that currently models are in flux and, for the moment, no support should be expected for migrations as models change. This will change when basic models gain stability.
For certain operations it will be useful to have accounts and superusers to work with. There are a few ways to add a superuser. For interactive use, the createsuperuser action is usually straightforward enough:
pipenv run python manage.py createsuperuser --email admin@example.com --username admin
Entering the password twice on prompting is currently required. If the options for --username and --email are skipped, the command will request these details first.
pipenv run python manage.py runserver
Amongst the initial output of that command will be something like:
Starting development server at http://127.0.0.1:8000/ Quit the server with CONTROL-C.
Currently there is not much to see at the specified location. More work has been done on the core API. The following views may be of interest as you explore:
These paths are subject to change.
Unit tests are currently being written with the standard unittest framework. This may be replaced with pytest.
Running the tests require a little extra setup:
pipenv install --dev
after which the tests may be run with the following command:
pipenv run python manage.py test
The Selenium tests currently require that Firefox is installed and geckodriver is also on the path. If you
PLATFORM_EXT="linux64.tar.gz"
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
chmod +x "$BIN_LOCATION"/geckodriver
If $BIN_LOCATION is on the system path, and the development server is running, it should be possible to run the integration tests.
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.
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