# HG changeset patch # User Branko Majic # Date 2017-12-19 14:39:12 # Node ID 827c719a42ed50c6324cb2c27520a1c5d2a82855 # Parent 0cdd159291b8187948142bf4b972c63b5d0fdfae CONNT-28: Updates to documentation, requirements handling, and minor fixes: - Fixed syntax error in MANIFEST.in file for recursive-exclude. - Merged the about section from documentation into the README file. Documentation now references README file instead of duplicating the data. Minor formatting and wording fixes were made as well. - Updated Sphinx configuration to use same string for both release and version (deduplicate it a bit). - Added a new, develoment-related, section to the documentation. Describes how to set-up the development environment, as well as some maintenance tasks. - Updated quickstart instructions so they actually work. Switched to using the pip install from PyPI instead of repository. - Introduced pip-tools use for the development requirements file. - Switched to using more fixed requirements in the setup.py. - Removed test requirements from the setup.py. diff --git a/MANIFEST.in b/MANIFEST.in --- a/MANIFEST.in +++ b/MANIFEST.in @@ -27,4 +27,4 @@ recursive-include conntrackt/templates * recursive-include docs * recursive-include requirements * recursive-exclude * *.py[co] -recursive-exclude docs/_build \ No newline at end of file +recursive-exclude docs/_build * \ No newline at end of file diff --git a/README.rst b/README.rst --- a/README.rst +++ b/README.rst @@ -8,32 +8,61 @@ Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. -Conntrackt -========== +About Django Conntrackt +======================= -Conntrackt (Connection Tracker) is a simple Django application for tracking -connection requirements between different entities in a network. +Django Conntrackt is a simple application targeted at system +administrators and integrators that deploy servers at client's +premises that need a way to keep track of required network +connectivity. -The application was written with intention to be used by system adminstrators -and integrators that deploy servers on customer premises, and need to keep tight -track of possible communication links between different entities in the -project. +Application allows tracking of required network communications between +different servers, routers, client workstations, and even whole +networks/sub-networks. In addition to keeping track of connections, the application has the ability to generate simple *iptables* rules based on the connections specified. The generated rules can be easily applied using the *iptables-restore* utility. +At time of this writing, Django Conntrackt is compatible with the +following Django and Python versions: + +- *Python 2.7.x* +- *Django 1.5.x* + + +Why was this application created? +--------------------------------- + +The application was created in order to alleviate painful and error prone +tracking of IP addresses and network communications inside of spreadsheet +files. Another reason was the need to create simple iptables rules based on this +information with as little hassle as possible. + +The *iptables* generation requirements for Django Conntrackt were farily simple, +and do not include any complex functionality. It all boils down to rejecting all +communication except for explicitly defined links. + Features -======== +-------- -In short, Conntrackt provides support for the following: +Django Conntrackt sports a number of useful features for system administrators +and integrators: -* Multiple independent projects -* Grouping entities inside of project by location -* Entities can be individual devices or networks -* Entities can have multiple network interfaces -* *iptables* rule generation (per-entity/location/project) +* Managing entities through multiple projects (separating the entities + per-project basis). +* Grouping entities inside of a project in one or more locations (which can be + either logical or physical). +* Specifying entities that represent servers, routers, workstations, networks, + subnets or any other networked device or abstraction within a network. +* Specifying multiple network interfaces for each entity. +* Specifying the communication link between two entities, which includes + information such as protocol and port. +* Generation of *iptables* rules for devices based on GNU/Linux that can be + consumed by the *iptables-restore* utility. +* Generation of *iptables* rules on per-location/project basis (multiple + *iptables* rule files inside of a single *ZIP* file). For more information, please have a look at full documentation at one of the following websites: @@ -42,7 +71,7 @@ following websites: License -======= +------- Django Conntrackt *application* is licensed under the terms of GPLv3, or (at your option) any later version. You should have received the full copy of the @@ -61,8 +90,7 @@ http://creativecommons.org/licenses/by-s The following third-party libraries are included as part of Django Conntrackt, but are distributed under their own license: -Bootstrap (sub-directory **conntrackt/static/bootstrap**) - Apache License v2.0 -jQuery (file **conntrackt/static/jquery-min.js**) - MIT License +- Bootstrap (sub-directory **conntrackt/static/bootstrap**), under + Apache License v2.0. +- jQuery (file **conntrackt/static/jquery-min.js**), under MIT License. diff --git a/docs/about.rst b/docs/about.rst --- a/docs/about.rst +++ b/docs/about.rst @@ -7,45 +7,4 @@ http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. - -About Django Conntrackt -======================= - -Django Conntrackt is a simple application intended to provide system -administrators and integrators that deploy servers at client's premises to -easily keep track of required networ communications between different servers, -routers, client workstations, and even whole networks/sub-networks. - - -Why was this application created? ---------------------------------- - -The application was created in order to alleviate painful and error prone -tracking of IP addresses and network communications inside of spread-sheet -files. Another reason was the need to create simple iptables rules based on this -information with as little hassle as possible. - -The *iptables* generation requirements for Django Conntrackt were farily simple, -and do not include any complex functionality. It all boils down to rejecting all -communication except for explicitly defined links. - - -Features --------- - -Django Conntrackt sports a number of useful features for system administrators -and integrators: - -* Managing entities through multiple projects (separating the entities - per-project basis). -* Grouping entities inside of a project in one or more locations (which can be - either logical or physical). -* Specifying entities that represent servers, routers, workstations, networks, - subnets or any other networked device or abstraction within a network. -* Specifying multiplel network interfaces for each entity. -* Specifying the communication link between two entities, which includes - information such as protocol and port. -* Generation of *iptables* rules for devices based on GNU/Linux that can be - consumed by the *iptables-restore* utility. -* Generation of *iptables* rules on per-location/project basis (multiple - *iptables* rule files inside of a *ZIP* file. +.. include:: ../README.rst diff --git a/docs/conf.py b/docs/conf.py --- a/docs/conf.py +++ b/docs/conf.py @@ -60,9 +60,9 @@ copyright = u'2013, Branko Majic' # built documents. # # The short X.Y version. -version = '0.2' +version = '0.2-dev' # The full version, including alpha/beta/rc tags. -release = '0.2' +release = version # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/development.rst b/docs/development.rst new file mode 100644 --- /dev/null +++ b/docs/development.rst @@ -0,0 +1,160 @@ +.. Copyright (C) 2017 Branko Majic + + This file is part of Django Conntrackt documentation. + + This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 + Unported License. To view a copy of this license, visit + http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative + Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA. + + +.. _development: + +Development +=========== + +This section provides an overview of how to take care of Django +Conntrackt development, including instructions on how to get started, +procedures, and common tools. + +Instructions are primarily aimed at use of Debian Stretch (as of time +of this writing). If you are running a different distribution or OS, +you will need to modify the instructions to suit your environment. + + +Preparing development environment +--------------------------------- + +Perform the following steps in order to prepare development +environment: + +1. Ensure that the following system packages are available on the + system: + + - `Python 2.7.x `_ + - `Graphviz `_ + - `virtualenv `_ + - `virtualenvwrapper + `_ + + Under Debian GNU/Linux it should be easy to install all the + necessary dependencies with command (provided you have sudo set-up, + otherwise run command as ``root`` without ``sudo``): + + .. warning:: + Don't forget to start a new shell in order to be able to use the + virtualenvwrapper. + + :: + + sudo apt-get install python2.7 graphviz mercurial virtualenv virtualenvwrapper + +2. Clone the application repository:: + + mkdir ~/projects/ + hg clone https://code.majic.rs/conntrackt/ ~/projects/conntrackt + +3. Set-up a new virtual environment:: + + mkvirtualenv -a ~/projects/conntrackt/ conntrackt + +4. Install required packages in the virtual environment:: + + workon conntrackt && pip install -r ~/projects/conntrackt/requirements/development.txt + + +Development/test Django project +------------------------------- + +*Django Contrackt* comes with a test Djanbo project which can be used +out-of-the-box once database has been initialised. + +Once the development environment has been set-up, you can set-up its +database with:: + + workon conntrackt + cd projtest/ + ./manage.py syncdb + ./manage.py migrate + +Once the database has been set-up, run the development server with:: + + workon conntrackt + cd projtest/ + ./manage.py runserver + +To access the application via started development server, simply point +your browser to http://localhost:8000/conntrackt/ . + + +Running tests +------------- + +The application is well covered with various (primarily unit) tests, +and the tests can be easily run via the supplied test/development +projects. Once the development environment has been set-up, tests can +be easily run with:: + + workon conntrackt + cd ~/projects/conntrackt/projtest/ + ./manage.py test conntrackt + + +Keeping installation and development requirements up-to-date +------------------------------------------------------------ + +There are two different types of (``pip``) requirements to keep in +mind while developing the application: + +- Package installation requirements, specified in ``setup.py``. +- Development requirements, maintained in dedicated requiremnts files. + +Distinction exists in order to allow faster start-up with the +development environment, as well as to ensure that during the +installation of package no side-effects are encountered due to +dependencies being too lax or untested. + +Base installation requirements are preserved within the ``setup.py`` +configuration script and are updated on as-needed basis by +hand. Packages within are pinned to stable releases required by +Conntrack to properly operate. For example, Django version is fixed to +reduce chance of running application against a wrong Django version. + +Development requirements duplicate the information stored within +``setup.py``, but also introduce some addtional tools required for +running tests, or tools that simply make the life easier. + +Development requirements are kept up-to-date via ``pip-compile`` from +`pip-tools `_. + +The input into the tool are the ``.in`` files located within the +requirements sub-directory: + +- ``base.in``, which reflects requirements outlined within the + ``setup.py``. +- ``development.in``, which includes the base requirements, as well as + additional ones needed for the normal development process. +- ``test.in``, which includes the base requirements, as well as + additional ones needed to run the tests. + +These input files are maintained by hand as well. However, the +resulting requirements ``.txt`` files are updated via the +``pip-compile`` tool. In order to sync changes in ``.in`` files, or to +update the requirements, simply run commands:: + + workon conntrackt + pip install pip-tools + pip-compile --upgrade ./requirements/development.in + pip-compile --upgrade ./requirements/test.in + +Afterwards you can commit the changes via standard Mercurial tools +(make sure the new requirements do not break the development/testing). + +Should you wish to, you can also opt to use the ``pip-sync`` utility +to keep your development environment in sync with the requirements +file. Just keep in mind that it will uninstall any package not listed +in requirements, and that it will force package versions from the +requirements file:: + + workon conntrackt + pip-sync ./requirements/development.txt diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -63,6 +63,7 @@ Contents installation quickstart usage + development releasenotes diff --git a/docs/quickstart.rst b/docs/quickstart.rst --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -17,13 +17,12 @@ This chapter provides quick-start instru Debian/Ubuntu ------------- -Install the *pip* utility:: - - sudo apt-get install pip +Install the required distribution packages:: -Install the *virtualenv* and *virtualenvwrapper*:: + sudo apt-get install python2.7 graphviz virtualenv virtualenvwrapper - sudo apt-get install python-virtualenv virtualenvwrapper +Open up a new shell to make sure the ``virtualenvwrapper`` is now +active. Create the virtual environment for testing Django Conntrackt:: @@ -32,7 +31,7 @@ Create the virtual environment for testi Install Django Conntrackt with its requirements:: workon conntrackt - pip install -e hg+http://code.majic.rs/conntrackt#egg=conntrackt + pip install django-conntrackt .. warning:: @@ -82,7 +81,9 @@ set-up the URLs for the admin website an Set-up the database for the project:: + cd conntrackt_test/ python manage.py syncdb + python manage.py migrate You will be prompted to provide some additional information: diff --git a/requirements/base.in b/requirements/base.in new file mode 100644 --- /dev/null +++ b/requirements/base.in @@ -0,0 +1,37 @@ +# +# Copyright (C) 2017 Branko Majic +# +# This file is part of Django Conntrackt. +# +# Django Conntrackt is free software: you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the Free +# Software Foundation, either version 3 of the License, or (at your option) any +# later version. +# +# Django Conntrackt is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# Django Conntrackt. If not, see . +# + +# Convenience mixins for Django (for authentication etc). +django-braces~=1.12.0 + +# Convenience tools for controlling rendering of forms while embracing DRY. +django-crispy-forms~=1.7.0 + +# Web framework used by application. +django~=1.5.0 + +# Library for programatic calculation of colours (contrasts, +# inversions etc). +palette~=0.2.0 + +# Interaface towards Graphviz for chart generation. +pydot~=1.2.0 + +# Library for data migration in case of model changes. +south~=1.0.0 diff --git a/requirements/base.txt b/requirements/base.txt --- a/requirements/base.txt +++ b/requirements/base.txt @@ -1,27 +1,13 @@ -# -# Copyright (C) 2013 Branko Majic -# -# This file is part of Django Conntrackt. # -# Django Conntrackt is free software: you can redistribute it and/or modify it -# under the terms of the GNU General Public License as published by the Free -# Software Foundation, either version 3 of the License, or (at your option) any -# later version. +# This file is autogenerated by pip-compile +# To update, run: +# +# pip-compile --output-file base.txt base.in # -# Django Conntrackt is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more -# details. -# -# You should have received a copy of the GNU General Public License along with -# Django Conntrackt. If not, see . -# - - -django~=1.5.0 -South -django-braces -django-crispy-forms +django-braces==1.12.0 +django-crispy-forms==1.7.0 +django==1.5.12 palette==0.2 -pyparsing==1.5.7 pydot==1.2.3 +pyparsing==2.2.0 # via pydot +south==1.0.2 diff --git a/requirements/development.in b/requirements/development.in new file mode 100644 --- /dev/null +++ b/requirements/development.in @@ -0,0 +1,35 @@ +# +# Copyright (C) 2017 Branko Majic +# +# This file is part of Django Conntrackt. +# +# Django Conntrackt is free software: you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the Free +# Software Foundation, either version 3 of the License, or (at your option) any +# later version. +# +# Django Conntrackt is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# Django Conntrackt. If not, see . +# + +-r base.in + +# Used for generating test code coverage report. +coverage~=4.4.0 + +# Convenience test runner tailored for running Django tests. +django-discover-runner~=0.3.0 + +# Used for dynamic generation of fixture data in tests. +factory_boy~=2.1.0 + +# Used for mocking in unit tests. +mock~=1.3.0 + +# Used for building documentation. +sphinx~=1.6.0 \ No newline at end of file diff --git a/requirements/development.txt b/requirements/development.txt --- a/requirements/development.txt +++ b/requirements/development.txt @@ -1,23 +1,37 @@ -# -# Copyright (C) 2013 Branko Majic -# -# This file is part of Django Conntrackt. # -# Django Conntrackt is free software: you can redistribute it and/or modify it -# under the terms of the GNU General Public License as published by the Free -# Software Foundation, either version 3 of the License, or (at your option) any -# later version. +# This file is autogenerated by pip-compile +# To update, run: +# +# pip-compile --output-file ./requirements/development.txt ./requirements/development.in # -# Django Conntrackt is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more -# details. -# -# You should have received a copy of the GNU General Public License along with -# Django Conntrackt. If not, see . -# - - --r base.txt -coverage -django-discover-runner +alabaster==0.7.10 # via sphinx +babel==2.5.1 # via sphinx +certifi==2017.11.5 # via requests +chardet==3.0.4 # via requests +coverage==4.4.2 +django-braces==1.12.0 +django-crispy-forms==1.7.0 +django-discover-runner==0.3 +django==1.5.12 +docutils==0.14 # via sphinx +factory-boy==2.1.2 +funcsigs==1.0.2 # via mock +idna==2.6 # via requests +imagesize==0.7.1 # via sphinx +jinja2==2.10 # via sphinx +markupsafe==1.0 # via jinja2 +mock==1.3.0 +palette==0.2 +pbr==3.1.1 # via mock +pydot==1.2.3 +pygments==2.2.0 # via sphinx +pyparsing==2.2.0 # via pydot +pytz==2017.3 # via babel +requests==2.18.4 # via sphinx +six==1.11.0 # via mock, sphinx +snowballstemmer==1.2.1 # via sphinx +south==1.0.2 +sphinx==1.6.5 +sphinxcontrib-websupport==1.0.1 # via sphinx +typing==3.6.2 # via sphinx +urllib3==1.22 # via requests diff --git a/requirements/test.in b/requirements/test.in new file mode 100644 --- /dev/null +++ b/requirements/test.in @@ -0,0 +1,20 @@ +# +# Copyright (C) 2013 Branko Majic +# +# This file is part of Django Conntrackt. +# +# Django Conntrackt is free software: you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the Free +# Software Foundation, either version 3 of the License, or (at your option) any +# later version. +# +# Django Conntrackt is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more +# details. +# +# You should have received a copy of the GNU General Public License along with +# Django Conntrackt. If not, see . +# + +-r development.in diff --git a/requirements/test.txt b/requirements/test.txt --- a/requirements/test.txt +++ b/requirements/test.txt @@ -1,25 +1,37 @@ -# -# Copyright (C) 2013 Branko Majic -# -# This file is part of Django Conntrackt. # -# Django Conntrackt is free software: you can redistribute it and/or modify it -# under the terms of the GNU General Public License as published by the Free -# Software Foundation, either version 3 of the License, or (at your option) any -# later version. +# This file is autogenerated by pip-compile +# To update, run: +# +# pip-compile --output-file ./requirements/test.txt ./requirements/test.in # -# Django Conntrackt is distributed in the hope that it will be useful, but -# WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or -# FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more -# details. -# -# You should have received a copy of the GNU General Public License along with -# Django Conntrackt. If not, see . -# - - --r base.txt -coverage +alabaster==0.7.10 # via sphinx +babel==2.5.1 # via sphinx +certifi==2017.11.5 # via requests +chardet==3.0.4 # via requests +coverage==4.4.2 +django-braces==1.12.0 +django-crispy-forms==1.7.0 django-discover-runner==0.3 -factory_boy==2.1.2 +django==1.5.12 +docutils==0.14 # via sphinx +factory-boy==2.1.2 +funcsigs==1.0.2 # via mock +idna==2.6 # via requests +imagesize==0.7.1 # via sphinx +jinja2==2.10 # via sphinx +markupsafe==1.0 # via jinja2 mock==1.3.0 +palette==0.2 +pbr==3.1.1 # via mock +pydot==1.2.3 +pygments==2.2.0 # via sphinx +pyparsing==2.2.0 # via pydot +pytz==2017.3 # via babel +requests==2.18.4 # via sphinx +six==1.11.0 # via mock, sphinx +snowballstemmer==1.2.1 # via sphinx +south==1.0.2 +sphinx==1.6.5 +sphinxcontrib-websupport==1.0.1 # via sphinx +typing==3.6.2 # via sphinx +urllib3==1.22 # via requests diff --git a/setup.py b/setup.py --- a/setup.py +++ b/setup.py @@ -21,18 +21,23 @@ import os from setuptools import setup, find_packages -from pip.req import parse_requirements README = open(os.path.join(os.path.dirname(__file__), 'README.rst')).read() -INSTALL_REQUIREMENTS = [str(r.req) for r in parse_requirements("requirements/production.txt", session='hack')] -TEST_REQUIREMENTS = [str(r.req) for r in parse_requirements("requirements/test.txt", session='hack')] +INSTALL_REQUIREMENTS = [ + "django-braces~=1.12.0", + "django-crispy-forms~=1.7.0", + "django~=1.5.0", + "palette~=0.2.0", + "pydot~=1.2.0", + "south~=1.0.0", +] # allow setup.py to be run from any path os.chdir(os.path.normpath(os.path.join(os.path.abspath(__file__), os.pardir))) setup( name='django-conntrackt', - version='0.2', + version='0.2-dev', packages=find_packages(exclude=["projtest", "projtest.*"]), include_package_data=True, license='GPLv3+', @@ -42,7 +47,6 @@ setup( author='Branko Majic', author_email='branko@majic.rs', install_requires=INSTALL_REQUIREMENTS, - tests_require=TEST_REQUIREMENTS, classifiers=[ 'Development Status :: 4 - Beta', 'Environment :: Web Environment',