# Getting Setup ## Overview The basic setup includes : * Creating a [Linux](http://distrowatch.com/) [Virtual Machine](http://en.wikipedia.org/wiki/Virtual_machine) * Installing necessary pre requisite applications * Install and set up [Django server](https://www.djangoproject.com/) * Set up and cloning of the [Git](http://git-scm.com/) repository * Prepping the database * Connecting it all together * Setup of a development environment * Development Pointers ## Virtual Machine Setup ### VirtualBox Setup [VirtualBox](https://www.virtualbox.org/) is a container for Virtual Machines that allows you to easily setup and deploy virtual machines on your local computer. VirtualBox can be downloaded [here](https://www.virtualbox.org/wiki/Downloads). Follow the instructions for your specific system to install. Avoid using distro based installers since they normally install older versions, and there are issues using v4.3.0 After installing Virtual Box create a new VM with the big blue New button. Name it whatever and set the type to be Linux and Version to Ubuntu(64 bit). By default the machine is only given a small amount of RAM, so up this to the GB range. Normally 50%-75% of maximum should be fine. After memory setup create a new virtual harddrive somewhere on the machine. VDI format should be solid. Choose dynamically allocated so that it does not consume hard drive space until the situation calls for it. Pick an appropriate location to save the virtual drive and give it about 100GB for the sake of overkill. It should never actually take up this much space. After creating the new VM, highlight it in the VirtualBox window and hit the setting button. In the General section, on the Advanced tab, Enable shared Clipboard and Drag'n'Drop as Bidirectional so interaction with the client machine is smoother. In the System section, on the Processor tab, give the VM access to as many processors as your system allows. Also enable PAE/NX. In the Display section, on the Video tab, Max out the video memory, and have Monitor Count match the number of machines you are using. Also enable Acceleration if possible. Those are all the settings that should need to be modified for now. ### Linux Installation Since many packages need to be installed and it would be very difficult to manage this accross operating systems, we recommend and only give instructions for [Debian-family](http://distrowatch.com/search.php?basedon=Debian) Linux machines. This includes Debian, Ubuntu, Linux Mint, and most distributions that have come from them. The important thing is have a Linux OS with apt-get. A full listing of Linux distributions can be found [here](http://distrowatch.com/). Find a suitable OS and download an ISO image for an installer. After downloading an iso for the installer, go to the settings of the VM you created, go to the Storage Tab, and hit the button for adding a CD. Select the Iso you downloaded, hit okay, and then hit the Start button for the VM to begin installation. Follow all prompts until you have an installed Linux OS ### Guest Additions After installing the OS, the screen will probably be pretty small and there may be some issues with video and general performance. There is a software called virtual box guest additions that helps to fix these issues. You can download it with sudo apt-get install virtualbox-guest-x11. After installing restart the Virtual Machine. If the command line fails, you can also go to the Devices tab in VirtualBox and select Install Guest Additions CB image. This will force an installation as a CD in the vm ## Pre-Requisites ### Python alias There are two major incompatible versions of Python, 2.7 and 3.x. You can run 2.7 by entering 'python' into a command line. 3.x can be run with 'python3'. To make it simpler you can set up a Bash alias. In your home directories .bashrc file addd the line 'alias python=python3'. Log out and back in and running python should show the python 3 REPL. ### Pip [Pip](https://pypi.python.org/pypi/pip) is a package management system for Python. It allows for easy installation of many Python packages. We can install Pip for python3 by using sudo apt-get install python3-pip. This will allow us to use the pip3 install command for the rest of this process. If you see a functionality that requires a python package, make sure to use pip3 instead of pip. Instructions online often only reference the latter. ### MySQL Client Django allows you to have Python communicate with multiple database backends. Since we are using MySQL as a DB, we need to install a driver to allow them to connect. The default is [mysqlclient](https://pypi.python.org/pypi/mysqlclient). This is the interface that is recommended by Django. First, the libraries behind it need to be installed with sudo apt-get install python-dev libmysqlclient-dev Then, install the client with sudo pip3 install mysqlclient ### Libjpeg [Libjpeg](http://libjpeg.sourceforge.net/) is used to find out information about JPeg images by Django. It can be installed with sudo apt-get install libjpeg-dev ### Pillow [Pillow](https://pypi.python.org/pypi/Pillow/) is an extention of the Python Imaging Library. It is used by Django for the processing of Images and ImageFields in the system. It can be installed with sudo pip3 install pillow ### PyYAML [PyYAML](http://pyyaml.org/) is a tool for processing YAML in Python. Django allows for database data to be exported in different formats. Since YAML is most human friendly it has been selected to be the format for our database fixtures. It can be installed through sudo pip3 install pyyaml ### Epydoc [Epydoc](http://epydoc.sourceforge.net/) is a tool used for creating Python documentation. Django has a built in documentation system which is used, and this supplements Django's tool where it is lacking. In can be installed with sudo apt-get install python-epydoc ### Docutils Django's built in documentation system requires a tool called [Docutils](http://docutils.sourceforge.net/). It is used for processing [reStructuredText](http://docutils.sourceforge.net/rst.html) It can be installed with sudo apt-get install python3-docutils ### NPM [NPM](https://www.npmjs.com/) is the Node Package Manager. It allows for a user to download server-side javascript tools which run using the [Node.js](https://nodejs.org/) platform. Some tools used on this project require Node tools, so this manager must be installed by running sudo apt-get install npm ### http-server [Http-server](https://www.npmjs.com/package/http-server) is light way command line tool for running a http-server. In this project it is used to host the epydoc generated API documentation. It can be installed with sudo npm install http-server -g ### yuidoc [YUIDoc](http://yui.github.io/yuidoc/) is a documentation generation tool for Javascript. It is used to generate and server a web based API documentation of JS files. It can be installed with sudo npm install yuidocjs -g ## Django Setup ### Install Django [Django](https://www.djangoproject.com/) Is a Model-View-Template framework for Python. It allows for more effective development of Python websites. It is the core technology of this entire project. It can be installed with sudo pip3 install django ### Install Django-localflavor [Django-localflavor](https://github.com/django/django-localflavor) is a Django plugin that gives support for different region specific data. In this project it is used to store US State info in a Form/Model. It can be installed with sudo pip3 install django-localflavor ### Install Django-widget-tweaks [Django-widget-tweaks](https://pypi.python.org/pypi/django-widget-tweaks) is a Django plugin that tries to help make django form templates more friendly. It allows one to do more customized rendering of Django form fields and is used in this project to apply css classes to form inputs. It can be installed with sudo pip3 install django-widget-tweaks ## Database Setup ### Install MySQL [MySQL](https://www.mysql.com/) is one of the worlds most popular relational database systems. Its community support, fact that it is free, and its integration in web apps has made this the choice for our project. It can be downloaded with sudo apt-get install mysql-server. The default user should be set to 'root', and default password to 'NewAppearances' for development so that one set of settings.py can be used. ### Configure MySQL A database needs to be created for the project. Log into mysql with the command mysql -u root -p which will open a new prompt. In the prompt, enter 'create database NewAppearances;' to prepare the database for the project. ### Install MySQL Workbench [MySQL Workbench](http://www.mysql.com/products/workbench/) is a GUI that helps work with MySQL databases more effectively. It is not mandatory, but if you'd like to use it, you can install it with sudo apt-get install mysql-workbench. After installing you can connect to the localhost server to ensure the NewAppearances database appears. ## Repo Setup ### Install Git [Git](http://git-scm.com/) is a distributed version control management system. It allows for a solid level of control over source code, and has a solid ecosystem with overall users and specifically through [GitHub](https://github.com/) and [Bitbucket](https://bitbucket.org/) In can be installed through sudo apt-get install git ### Forking Repo The current repo is stored [here](https://bitbucket.org/philsim7/newappearances). If you select the form option you can put in settings and hit the fork repository button to create a new version of the repo for your own account. This repo will be used for future commits/pushes and will be merged to the main code repository through pull requests. Contact an administrator if you need access to the repository. ### Cloning Repo Once you have a repository forked you can clone it to your local machine. In the upper right hand corner of the repository view you'll see a bar that says HTTPS and a url for the repo. In your VM run git clone and this will clone your repository to your local machine ### Setup Remotes Go back to the [main repo](https://bitbucket.org/philsim7/newappearances). Copy the text from the https section again and run the following git remote add upstream Now if you run git pull upstream master it will add all code from the master repo to your local fork. To add code to master you should make changes, commit them, and run git push origin master. This will add the commits to your fork which can be merged into master by going to your fork in BitBucket, going to the Pull Requests screen, and hitting the Create pull Request button. People with write access will review, comment, and if it calls for it, merge, your code to the master repo. ## Connecting Together ### Setup Database Once Django, MySQL, all required packages, and the repo is set up, you can use Django to set up the database. Go to the project root and run python manage.py makemigrations followed by python manage.py migrate. Once this has completed the root structure for the database should be complete. To load test data go to the tools directory and run ./loadData.sh ### Running Application Manage.py handles most functionality in Django. Once everything has been setup the application can be launched with python manage.py runserver. Once this has been started you can hit port 8000 on [localhost](http://127.0.0.1:8000/) to access the application. Ensure all pages display as expected. ## Development Environment ### PyCharm Download The entirety of [JetBrains'](https://www.jetbrains.com/) suite of IDEs are solid across various languages. For this Project we support [PyCharm](https://www.jetbrains.com/pycharm) as the IDE. It can be downloaded through the previous link. If you have the cash for Pro Edition, it is great. Otherwise the Community Edition is available for all. ### PyCharm Install PyCharm downloads as a compressed tar file. Extract this somewhere and access the extracted location through the command line. PyCharm requires a Java JDK installed so run sudo apt-get install openjdk-7-jre so that there is a viable java version on the machine. Find the bin folder in the extracted PyCharm directory and run ./pycharm.sh. This should properly install PyCharm on your machine. Open the project repo in PyCharm and it should automatically determine that it is a Django project. ### Plugin Setup There are many plugins for PyCharm. If you go to File > Settings > Plugins you can see those currently supported. Clicking the Browse repositories... button will allow for new installs. For this project it can be helpful to install .ignore, BashSupport, and Markdown ### Javascript Library Setup Javascript libraries can be added for typeahead/processing in PyCharm. You can access this by going to File > Settings > Languages & Frameworks > Javascript > Libraries. The Download button allows for the downloading of Repos. All JS libraries available in [Tools](../Development/Tools) should be added through the Download functionality.