Changeset - d7c64b3800af
Parent rev.
Child rev.
[Not reviewed]
default
0 5 1
Branko Majic (branko) - 6 years ago 2017-12-22 12:39:52
branko@majic.rs
CONNT-25: Updated documentation:

- Marked Django 1.11.x as the only supported Django version.
- Updated some copyright notices.
- Updated installation and quick-start instructions for use with new
version of Django.
- Removed unneeded warning about pip version.
- Updated instructions to emphasize that 'crispy_forms' must be
included in list of installed applications.
- Added dedicated section for upgrade instructions. Covered some
general principles and upgrade from 0.3.x to 1.0.x.
- Updated release notes.
- Added information about Graphviz being the external dependency.
6 files changed with 99 insertions and 51 deletions:
README.rst
6
1
docs/index.rst
2
1
docs/installation.rst
15
17
docs/quickstart.rst
2
28
docs/releasenotes.rst
5
4
docs/upgrading.rst
69
0 comments (0 inline, 0 general)
README.rst
➞
Show inline comments
 
@@ -19,25 +19,30 @@ connectivity.
 
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*

			




	
	
	
		
 
- *Django 1.11.x*

			




	
	
	
		
 

			




	
	
	
		
 
In addition, *Django Conntrackt* uses the following external

			




	
	
	
		
 
dependencies:

			




	
	
	
		
 

			




	
	
	
		
 
- `Graphviz <https://graphviz.org/>`_

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
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

			




        

    


    
    

    

        

                

                    docs/index.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. Copyright (C) 2013 Branko Majic

			




	
	
	
		
 
.. Copyright (C) 2013-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.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Django Conntrackt documentation

			




	
	
	
		
 
===============================

			




	
	
	
		
 

			




	
	
		
 
@@ -59,24 +59,25 @@ jQuery (file **conntrackt/static/jquery-

			




	
	
	
		
 
  MIT License

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Contents

			




	
	
	
		
 
--------

			




	
	
	
		
 

			




	
	
	
		
 
.. toctree::

			




	
	
	
		
 
   :maxdepth: 2

			




	
	
	
		
 

			




	
	
	
		
 
   about

			




	
	
	
		
 
   installation

			




	
	
	
		
 
   quickstart

			




	
	
	
		
 
   upgrading

			




	
	
	
		
 
   usage

			




	
	
	
		
 
   development

			




	
	
	
		
 
   releaseprocedures

			




	
	
	
		
 
   releasenotes

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Indices and tables

			




	
	
	
		
 
==================

			




	
	
	
		
 

			




	
	
	
		
 
* :ref:`genindex`

			




	
	
	
		
 
* :ref:`modindex`

			




	
	
	
		
 
* :ref:`search`

			




        

    


    
    

    

        

                

                    docs/installation.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. Copyright (C) 2013 Branko Majic

			




	
	
	
		
 
.. Copyright (C) 2013-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.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Installation

			




	
	
	
		
 
============

			




	
	
	
		
 

			




	
	
	
		
 
Django Conntrackt can be installed through one of the following methods:

			




	
	
	
		
 
*Django Conntrackt* has the following prerequisites that need to be

			




	
	
	
		
 
satisfied on the operating system level:

			




	
	
	
		
 

			




	
	
	
		
 
- `Graphviz <https://graphviz.org/>`_, used for generating the

			




	
	
	
		
 
  diagrams.

			




	
	
	
		
 

			




	
	
	
		
 
*Django Conntrackt* can be installed through one of the following methods:

			




	
	
	
		
 

			




	
	
	
		
 
* Using *pip*, which is the recommended way for production

			




	
	
	
		
 
  websites.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Using pip

			




	
	
	
		
 
---------

			




	
	
	
		
 

			




	
	
	
		
 
In order to install latest stable release of Django Conntrackt using *pip*, use

			




	
	
	
		
 
the following command::

			




	
	
	
		
 

			




	
	
	
		
 
  pip install conntrackt

			




	
	
	
		
 

			




	
	
	
		
 
In order to install the latest development version of Django Conntrackt from

			




	
	
	
		
 
Mercurial repository, use the following command::

			




	
	
	
		
 

			




	
	
	
		
 
 pip install -e hg+http://code.majic.rs/conntrackt#egg=conntrackt

			




	
	
	
		
 

			




	
	
	
		
 
.. warning::

			




	
	
	
		
 

			




	
	
	
		
 
   You will need to update the ``pip`` installation in your virtual environment if you get the following error while running the above command::

			




	
	
	
		
 

			




	
	
	
		
 
     AttributeError: 'NoneType' object has no attribute 'skip_requirements_regex'

			




	
	
	
		
 

			




	
	
	
		
 
   You can update ``pip`` to latest version with::

			




	
	
	
		
 

			




	
	
	
		
 
     pip install -U pip

			




	
	
	
		
 

			




	
	
	
		
 
After this you should proceed to :ref:`configure your Django installation <configuring-django>`.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
.. _configuring-django:

			




	
	
	
		
 

			




	
	
	
		
 
Configuring your Django installation

			




	
	
	
		
 
====================================

			




	
	
	
		
 

			




	
	
	
		
 
Once the Django Conntrackt has been installed, you need to perform the following

			




	
	
	
		
 
steps in order to make it available inside of your Django project:

			




	
	
	
		
 

			




	
	
	
		
 
#. Edit your project's settings configuration file (``settings.py``), and update

			




	
	
	
		
 
   the ``INSTALLED_APPS`` to include applications ``south``, ``braces`` and ``conntrackt``.

			




	
	
	
		
 
#. Edit your project's settings configuration file (``settings.py``),

			




	
	
	
		
 
   and update the ``INSTALLED_APPS`` to include applications

			




	
	
	
		
 
   ``braces``, ``crispy_forms``, and ``conntrackt``.

			




	
	
	
		
 

			




	
	
	
		
 
#. Edit your project's URL configuration file (``urls.py``), and add the

			




	
	
	
		
 
   following line to the ``urlpatterns`` setting::

			




	
	
	
		
 

			




	
	
	
		
 
     url(r'^conntrackt/', include('conntrackt.urls')),

			




	
	
	
		
 

			




	
	
	
		
 
#. Create the necessary tables used for Django Conntrackt by running::

			




	
	
	
		
 

			




	
	
	
		
 
   ./manage.py syncdb

			




	
	
	
		
 
   ./manage.py migrate

			




	
	
	
		
 

			




	
	
	
		
 
After this the Django Conntrackt application will be available under the

			




	
	
	
		
 
``/conntrackt/`` path (relative to your Django project's base URL).

			




	
	
	
		
 

			




	
	
	
		
 
If you have enabled ``django.contrib.admin``, you should be able to add new

			




	
	
	
		
 
Conntrackt data through the admin interface.

			




	
	
	
		
 
If you have enabled ``django.contrib.admin``, you should be able to

			




	
	
	
		
 
add new Conntrackt data through admin interface as well - in addition

			




	
	
	
		
 
to native data entry provided by application.

			




        

    


    
    

    

        

                

                    docs/quickstart.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. Copyright (C) 2013 Branko Majic

			




	
	
	
		
 
.. Copyright (C) 2013-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.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Quick-start guide

			




	
	
	
		
 
=================

			




	
	
	
		
 

			




	
	
		
 
@@ -24,83 +24,57 @@ Install the required distribution packag

			




	
	
	
		
 
Open up a new shell to make sure the ``virtualenvwrapper`` is now

			




	
	
	
		
 
active.

			




	
	
	
		
 

			




	
	
	
		
 
Create the virtual environment for testing Django Conntrackt::

			




	
	
	
		
 

			




	
	
	
		
 
  mkvirtualenv conntrackt

			




	
	
	
		
 

			




	
	
	
		
 
Install Django Conntrackt with its requirements::

			




	
	
	
		
 

			




	
	
	
		
 
  workon conntrackt

			




	
	
	
		
 
  pip install django-conntrackt

			




	
	
	
		
 

			




	
	
	
		
 
.. warning::

			




	
	
	
		
 

			




	
	
	
		
 
   You will need to update the ``pip`` installation in your virtual environment if you get the following error while running the above command::

			




	
	
	
		
 

			




	
	
	
		
 
     AttributeError: 'NoneType' object has no attribute 'skip_requirements_regex'

			




	
	
	
		
 

			




	
	
	
		
 
   You can update ``pip`` to latest version with::

			




	
	
	
		
 

			




	
	
	
		
 
     pip install -U pip

			




	
	
	
		
 

			




	
	
	
		
 
Start a new Django Conntrackt project::

			




	
	
	
		
 

			




	
	
	
		
 
  django-admin.py startproject conntrackt_test

			




	
	
	
		
 

			




	
	
	
		
 
Edit configuration file ``conntrackt_test/conntrackt_test/settings.py`` to set-up

			




	
	
	
		
 
some basic settings:

			




	
	
	
		
 

			




	
	
	
		
 
#. Under ``DATABASES`` set parameter ``ENGINE`` to ``'django.db.backends.sqlite3'``.

			




	
	
	
		
 
#. Under ``DATABASES`` set parameter ``NAME`` to ``'conntrackt_test.sqlite'``.

			




	
	
	
		
 
#. Under ``INSTALLED_APPS`` uncomment the line ``'django.contrib.admin'``.

			




	
	
	
		
 
#. Under ``INSTALLED_APPS`` append lines::

			




	
	
	
		
 

			




	
	
	
		
 
     'south',

			




	
	
	
		
 
     'crispy_forms',

			




	
	
	
		
 
     'braces',

			




	
	
	
		
 
     'conntrackt',

			




	
	
	
		
 

			




	
	
	
		
 
#. Append the following lines to the end of the file::

			




	
	
	
		
 

			




	
	
	
		
 
     from django.conf.global_settings import TEMPLATE_CONTEXT_PROCESSORS

			




	
	
	
		
 
     TEMPLATE_CONTEXT_PROCESSORS += (

			




	
	
	
		
 
         "django.core.context_processors.request",

			




	
	
	
		
 
     )

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Edit the URL configuration file ``conntrackt_test/conntrackt_test/urls/.py`` to

			




	
	
	
		
 
set-up the URLs for the admin website and Conntrackt itself:

			




	
	
	
		
 

			




	
	
	
		
 
#. At the top of the file, add line ``from django.http import HttpResponseRedirect``.

			




	
	
	
		
 
#. Uncomment line ``from django.contrib import admin``.

			




	
	
	
		
 
#. Uncomment line ``admin.autodiscover()``.

			




	
	
	
		
 
#. Uncomment line ``url(r'^admin/', include(admin.site.urls)),``

			




	
	
	
		
 
#. Under ``urlpatterns`` append lines::

			




	
	
	
		
 

			




	
	
	
		
 
     url(r'^$', lambda r : HttpResponseRedirect('conntrackt/')),

			




	
	
	
		
 
     url(r'^conntrackt/', include('conntrackt.urls')),

			




	
	
	
		
 

			




	
	
	
		
 
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:

			




	
	
	
		
 

			




	
	
	
		
 
#. When prompted to create a superuser, answer ``yes``.

			




	
	
	
		
 
#. Provide the desired username when prompted for it.

			




	
	
	
		
 
#. Provide the desired e-mail address when prompted for it.

			




	
	
	
		
 
#. Provide the desired password for created user.

			




	
	
	
		
 

			




	
	
	
		
 
After this the project is fully configured to run Django Conntrackt. Run the

			




	
	
	
		
 
Django development server (good enough for testing, but don't use it in

			




	
	
	
		
 
production)::

			




	
	
	
		
 

			




	
	
	
		
 
  python manage.py runserver

			




	
	
	
		
 

			




	
	
	
		
 
You can now explore the functionality of Djang Conntrackt at::

			




	
	
	
		
 
  http://localhost:8000/

			




	
	
	
		
 

			




	
	
	
		
 
If you have any problems getting around and understanding how the applications

			




	
	
	
		
 
works, have a look at the :ref:`usage guide <usage>`.

			




	
	
	
		
 

			




        

    


    
    

    

        

                

                    docs/releasenotes.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
	
		
 
.. Copyright (C) 2013 Branko Majic

			




	
	
	
		
 
.. Copyright (C) 2013-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.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Release Notes

			




	
	
	
		
 
=============

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
dev

			




	
	
	
		
 
---

			




	
	
	
		
 

			




	
	
	
		
 
Breaking changes:

			




	
	
	
		
 

			




	
	
	
		
 
* Django Conntrackt now depends on Django 1.10. In addition to official

			




	
	
	
		
 
  Django documentation, there is a dedicated upgrade guide that deals

			




	
	
	
		
 
  with the most basic installation.

			




	
	
	
		
 
* Django Conntrackt now depends on Django 1.11. In addition to

			




	
	
	
		
 
  official Django documentation for project upgrades, there is a

			




	
	
	
		
 
  section describing what needs to be done in order to upgrade the

			




	
	
	
		
 
  application itself.

			




	
	
	
		
 
  [ `CONNT-25 <https://projects.majic.rs/conntrackt/issues/CONNT-30>`_ ]

			




	
	
	
		
 

			




	
	
	
		
 
New features/improvements:

			




	
	
	
		
 

			




	
	
	
		
 
* Updated jQuery used internally to version 3.2.1.

			




	
	
	
		
 
  [ `CONNT-30 <https://projects.majic.rs/conntrackt/issues/CONNT-30>`_ ]

			




	
	
	
		
 

			




	
	
	
		
 
Bug-fixes:

			




	
	
	
		
 

			




	
	
	
		
 
* Fixed minor issues in the release procedure documentation.

			




	
	
	
		
 
  [NO TICKET]

			




	
	
	
		
 
* Wrong version of Django Crispy Forms was required by the

			




        

    


    
    

    

        

                

                    docs/upgrading.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
new file 100644

			




	
	
	
		
 
.. 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.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Upgrading

			




	
	
	
		
 
=========

			




	
	
	
		
 

			




	
	
	
		
 
This section covers the necessary upgrade steps between different

			




	
	
	
		
 
versions.

			




	
	
	
		
 

			




	
	
	
		
 
In general, it is always useful to go thorugh the release notes to

			




	
	
	
		
 
ensure there no surprises are encountered during the upgrade.

			




	
	
	
		
 

			




	
	
	
		
 
Upgrading from one **patch version** to another (e.g. ``0.3.0`` to

			




	
	
	
		
 
``0.3.1``) should be safe, and should not require any additional steps

			




	
	
	
		
 
beyond installing new package version. Patch versions include only bug

			




	
	
	
		
 
and security-related fixes.

			




	
	
	
		
 

			




	
	
	
		
 
Upgrading from one **minor version** to another (e.g. ``0.2.0`` to

			




	
	
	
		
 
``0.3.0`` might require some small maintenance tasks, such as running

			




	
	
	
		
 
migrations, or refreshing the static files. In general no breaking

			




	
	
	
		
 
changes should be introduced, and downtime should be minimal.

			




	
	
	
		
 

			




	
	
	
		
 
Upgrading from one **major version** to another (e.g. ``0.3.1`` to

			




	
	
	
		
 
``1.0.0``) is likely to require a number of changes, and you should

			




	
	
	
		
 
make sure to review both the release notes, and any other documented

			




	
	
	
		
 
instructions outlined below.

			




	
	
	
		
 

			




	
	
	
		
 
Major version upgrades should be performed only for supported upgrade

			




	
	
	
		
 
paths. This usually means bringing your current installation to the

			




	
	
	
		
 
latest minor release version before jumping to the next major

			




	
	
	
		
 
release. Should you need to jump multiple versions, do it one step at

			




	
	
	
		
 
a time, following along with any necessary changes. Currently

			




	
	
	
		
 
supported upgrade paths are:

			




	
	
	
		
 

			




	
	
	
		
 
- From version ``0.3.x`` to version ``1.0.x``.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Upgrading from ``0.3.x`` to ``1.0.x``

			




	
	
	
		
 
-------------------------------------

			




	
	
	
		
 

			




	
	
	
		
 
Version ``1.0.x`` brings in a lot of changes related to dependency

			




	
	
	
		
 
upgrades. This is a big step in terms of Django versions (from Django

			




	
	
	
		
 
1.5.x to Django 1.11.x), with application functionality itself left

			




	
	
	
		
 
untouched.

			




	
	
	
		
 

			




	
	
	
		
 
In particular, since support for Django 1.5.x has been dropped, you

			




	
	
	
		
 
will need to upgrade your project to Django 1.11.x. Depending on your

			




	
	
	
		
 
project customisations, it may be easier to start a new project and

			




	
	
	
		
 
move over any relevant configuration to it.

			




	
	
	
		
 

			




	
	
	
		
 
For *Django Conntrackt* itself, at least the following changes must be

			




	
	
	
		
 
made:

			




	
	
	
		
 

			




	
	
	
		
 
- Removing ``south`` from list of installed applications in project

			




	
	
	
		
 
  settings. *Django Conntrackt* now utilises the native migrations.

			




	
	
	
		
 
- Run database migrations with::

			




	
	
	
		
 

			




	
	
	
		
 
    python manage.py migrate

			




	
	
	
		
 

			




	
	
	
		
 
- Ensure static data served by external server are up-to-date with::

			




	
	
	
		
 

			




	
	
	
		
 
    python manage.py collectstatic

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2023 by various authors & licensed under GPLv3.