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',