|
|
# Developer's Guide for GNUKhata Web Front-end
|
|
|
Welcome to this guide on programming GNUKhata front end.
|
|
|
As you are aware, GNUKhata is a core set of APIs containing all the business logic for book keeping, inventory and generating related reports.
|
|
|
As a result, programmers can write different type of front-ends by utilizing the same core logic.
|
|
|
This is a web app, i.e the web based front-end.
|
|
|
We are very happy to help you help us and the free software community for creating this free,(as in freedom ) professional quality and industry level accounting software.
|
|
|
To participate in the development of this web front end, you should first fulfill the prerequisites.
|
|
|
This will save your time and avoid any confusion on getting started or on certain aspect of the development/ programming.
|
|
|
Note that you can always join the [GNUKhata developers mailing list](https://www.freelists.org/list/gnukhata-devel) and discuss with us any difficulty or suggestion you have.
|
|
|
|
|
|
## Requirements
|
|
|
GNUKhata uses [Python programming language](www.python.org) for both it's core logic and the web based front-end.
|
|
|
In addition, you will need to be aware of concepts needed to write a web based application.
|
|
|
Here is a list of prerequisites along with brief description.
|
|
|
|
|
|
### GNU/Linux OS
|
|
|
Needless to say we exclusively use GNU/Linux operating system for our daily work and professional programming.
|
|
|
We are free software advocates and urge every one to use it, not just for the superior, faster and professional performance but also because it is a freedom technology.
|
|
|
GNU/Linux is the free (as in freedom ) OS and we recommend Ubuntu, Mint, or if you like the hacker stuff, Debian brands.
|
|
|
Note that GNUKhata works on Windows but all our programming and designing happens on the said OS.
|
|
|
|
|
|
### Gitlab account
|
|
|
One major aspect of a free and open source project is that it's source code is open and freely available to all.
|
|
|
You can copy, study, modify and share it with any one for any purpose.
|
|
|
However for professional management and quality assurance every project needs a core team in charge of the main source code. Any one can then make an exact copy of the original source code and make any changes to that copy.
|
|
|
Then such changes are submitted to the main repository (meaning the code base ). a merge request can be then sent where the core team members screen the submitted code for quality and see if the said task is properly done.
|
|
|
If all is well then the contribution is merged into the main repository.
|
|
|
There are several such free project management and collaboration tools.
|
|
|
One such is [Git Lab](www.gitlab.com) and that's what we use for GNUKhata.
|
|
|
You should make an account there and then follow the instructions in this guide for forking and cloning a copy of the source code for yourself.
|
|
|
You can also visit [Gitlab basics ](https://gitlab.com/help/gitlab-basics/README.md) to get started.
|
|
|
You may consider this as your entry into collaborative free software development in general and GNUKhata in particular.
|
|
|
### Python
|
|
|
|
|
|
[Python](www.python.org) is a very powerful, robust, scalable programming language. But having this power, it is extremely easy to learn.
|
|
|
You can enjoy learning this amazing programming language from [this easy book](http://openbookproject.net/thinkcs/python/english2e/index.html)
|
|
|
### Pyramid Web Framework
|
|
|
Writing every component by yourself all in great details takes a lot of time.
|
|
|
In addition if you were to write every little repeatable code and commonly used components like connectivity logic, data dynamics etc then no project can ever finish in time.
|
|
|
Web frameworks come to our rescue here.
|
|
|
A framework not just helps by providing skeleton code for most common tasks, but also ready to use infrastructure for connectivity database access etc.
|
|
|
We use [Pyramid web framework](http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial) for both our back-end and front-end.
|
|
|
Look at chapter 1,2,7,8,9,10,11 and 12 in particular in the book for quick understanding.
|
|
|
### JavaScript with jQuery
|
|
|
Most of the user interaction on the browser including clicking, selecting text, sending and receiving data from forms and related stuff is done using a browser based programming language called JavaScript.
|
|
|
You can get started by reading [this manual](http://www.w3schools.com/js/default.asp)
|
|
|
You can get comprehensive tutorials [here](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide)
|
|
|
|
|
|
|
|
|
We use the jQuery library of JavaScript for making our work easy.
|
|
|
You will need to learn this because most of the challenging work regarding user interaction is done using this library.
|
|
|
you can get started with jQuery basics by reading this [basic tutorial](http://www.w3schools.com/jquery/default.asp)
|
|
|
Most of the styling, layout etc is done using the Bootstrap CSS library.
|
|
|
Read the [basic tutorial](http://www.w3schools.com/bootstrap/default.asp) to know more about it.
|
|
|
|
|
|
----
|
|
|
### Installation
|
|
|
To install GNUKhata in development mode, there are a few things to understand.
|
|
|
First and for most, GNUKhata core is needed for which you will be building the web app.
|
|
|
Secondly, All dependencies related to Python based code will be installed in a virtual environment.
|
|
|
A virtual environment isolates your own personal copy of the Python programming language,
|
|
|
Also gives you freedom to have several copies and all this never affects the main Python setup.
|
|
|
In addition keep in mind that the core logic needs Postgresql database and a few other things to work.
|
|
|
As a web app developer, you may not need to know much about the core but knowing how to run it will be necessary.
|
|
|
We will first install the dependencies, then create the virtual environment and add the necessary Python libraries, incuding the Pyramid framework.
|
|
|
Then we clone our copy of gkcore and gkwebapp.
|
|
|
Note that to install libraries and to run GNUKhata, the virtual environment must be first activated.
|
|
|
Note also that steps given here should be followed completely. If any step is skipped it might result in GNUKhata not working at all or working improperly.
|
|
|
BE CAREFULL, You ARe WARNED!
|
|
|
|
|
|
All the following set of commands should be given in a terminal.
|
|
|
You can press alt + ctrl + t to get a terminal.
|
|
|
you will see the $ prompt as soon as the terminal opens.
|
|
|
Note: you have to press enter after completely typing every command.
|
|
|
Note: the $ sign is just provided to indicate a terminal, so please don't include it in your commands.
|
|
|
|
|
|
* Install python-virtualenv postgresql and dependencies using following command
|
|
|
|
|
|
> `$ sudo apt-get install python-virtualenv postgresql-9.5 python-dev libpq-dev git`
|
|
|
|
|
|
* if you are going to use Eclipse IDE then you will also need java, install it using:
|
|
|
|
|
|
> `$ sudo apt-get install openjdk-8-jdk `
|
|
|
|
|
|
* Create a python virtualenv in a directory using:
|
|
|
|
|
|
> `$ virtualenv gkenv `
|
|
|
|
|
|
* change directory to gkenv:
|
|
|
|
|
|
> `$ cd gkenv `
|
|
|
|
|
|
* Activate your virtualenv using:
|
|
|
|
|
|
> `source bin/activate`
|
|
|
|
|
|
* Install dependencies in the virtualenv using:
|
|
|
|
|
|
> `pip install pyramid pyramid_debugtoolbar psycopg2 odslib sqlalchemy waitress wsgicors requests monthdelta pyjwt pillow babel pycrypto openpyxl`
|
|
|
|
|
|
* Fork gkwebapp from https://git.fosscommunity.in/gnukhata/gkwebapp
|
|
|
|
|
|
* Fork gkcore from https://git.fosscommunity.in/gnukhata/gkcore
|
|
|
|
|
|
* Create and add your SSH key to gitlab by following this guide - https://git.fosscommunity.in/help/gitlab-basics/create-your-ssh-keys.md
|
|
|
|
|
|
* Clone gkwebapp and gkcore in your workspace using:
|
|
|
|
|
|
> `git clone gitlab@git.fosscommunity.in:<username>/gkwebapp.git`
|
|
|
|
|
|
>`git clone gitlab@git.fosscommunity.in:<username>/gkcore.git`
|
|
|
|
|
|
|
|
|
* Change directory to gkcore
|
|
|
|
|
|
* Look inside the directory. You must find files like gkutil.sh, setup.py, initdb.py and gkcore.ini
|
|
|
|
|
|
* Give permission to gkutil.sh file to execute and execute the same using:
|
|
|
|
|
|
> `chmod 755 gkutil.sh`
|
|
|
|
|
|
> `./gkutil.sh`
|
|
|
|
|
|
* Activate your virtual environment and run setup.py using:
|
|
|
|
|
|
> `python setup.py develop`
|
|
|
|
|
|
* Your environment will be checked for all the required libraries and the missing ones will be downloaded.
|
|
|
|
|
|
* Now we have to run initdb.py script. This will create tables in our database. To run this script we need to switch to a user 'gkadmin' which was created when we ran 'gkutil.sh' script.
|
|
|
|
|
|
> `sudo su gkadmin`
|
|
|
|
|
|
Activate your virtualenv and then run initdb.py.
|
|
|
|
|
|
> `python initdb.py`
|
|
|
|
|
|
* To run gkcore server in development mode use:
|
|
|
|
|
|
> `pserve gkcore.ini`
|
|
|
|
|
|
* Open another terminal and change directory to gkwebapp
|
|
|
* Activate virtualenv and run setup.py using
|
|
|
|
|
|
> `python setup.py develop`
|
|
|
|
|
|
* To run gkwebapp server in development mode use:
|
|
|
|
|
|
> `pserve development.ini` |
|
|
\ No newline at end of file |