INSTALL

Instructions to install Coinbox:
================================

# Linux systems

  * Create the `virtualenv`:

    $ virtualenv coinbox
    $ cd coinbox/
    $ source bin/activate
  
  * First of all, you most probably need to install PySide before continuing, because it will fail when installing automatically.
    If you check the docs, there'll be the exact directives. Here are two ways to do that on Linux: (it takes time)
    
    $ # AFAIK, you cannot use the distro's package manager because it will not be detected by pip.
    $ # Use `pip freeze | grep -i pyside` to check if it shows up, if it does then great.
    
    $ # Otherwise:
    
    $ pip install PySide
    
    $ # Or (if you want to make an egg and install many times)
    
    $ wget https://pypi.python.org/packages/source/P/PySide/PySide-1.2.1.tar.gz
    $ tar -xvzf PySide-1.2.1.tar.gz
    $ cd PySide-1.2.1
    $ python2.7 setup.py bdist_egg --qmake=/usr/bin/qmake-qt4
    $ # Wait... Get something to drink... Wait some more...
    $ easy_install dist/PySide-1.2.1-py2.7.egg
    $ pyside_postinstall.py -install
    $ cd ..
  
  * Just to check where we're at, you can run `pip freeze | less` and check that PySide is installed.
  
  * First, we download the setup script from github (this is equivalent to pressing the download button and unzipping):
  
    $ wget https://github.com/coinbox/coinbox-core/archive/master.zip -O install.zip
    $ unzip install.zip
    $ cd coinbox-core-master/
  
  * Here, you have the necessary files to install the "core".
    You can choose what to install exactly, or you can run this which downloads the rest and installs everything:
  
    $ make
  
  * (You can skip this) Otherwise, you have options to install only the core (and install the modules you want later):
  
    $ make install # This installs the core from the files you have
    $ make develop-git # This clones the core repository, and installs it in "develop" mode
    $ make develop # This installs the core from the files you have, but in "develop" mode
    
    $ make install-modules # This downloads and installs all the modules from github
    $ make develop-modules # This clones the repositories for all the modules and installs in "develop" mode
    $ make develop-modules-zip # This downloads zipballs of the repositories for all the modules and installs in "develop" mode
    
    $ # If you want to choose which modules to install/develop, you can use a similar command:
    $ env COINBOX_INSTALL_MODULES="currency auth" make -e develop-modules
    $ # Or even with the default install (don't forget the -e though)
    $ env COINBOX_INSTALL_MODULES="base currency sales" make -e
    
    $ # You can also override the COINBOX_GIT_BASE_URL and COINBOX_GIT_BRANCH from which to clone/zipball the repositories (look at the Makefile for more details)
    $ # And you can use COINBOX_UPGRADE to force the latest version of everything to be installed
    $ env COINBOX_UPGRADE=yes COINBOX_INSTALL_MODULES="base currency sales" make -e install-modules-zip
    $ env COINBOX_UPGRADE=yes make -e install-zip
  
  * To check that it all went good, first make sure your PC did not blow up after that command.
    Second, use `pip freeze | less` to check that "Coinbox-pos" is there, along with a couple other dependent packages.
    And you should also find "Coinbox-mod-XXX" for each module.
  
  * Okay so now, we should set some environment variables to know where to store everything.
     (The following commands are just an example)
     (You can skip this step, and if you do, the config files will be in $HOME/config)
     (Also, if you `pip install pyxdg`, these files will be in the standard paths of your system)
  
    $ cd ..
    $ # So now we are back to the virtualenv base directory
    $ # Either this:
    $ env COINBOX_LOCALE_DIR=$VIRTUAL_ENV COINBOX_DATA_DIR=$VIRTUAL_ENV COINBOX_CONFIG_DIR=$VIRTUAL_ENV coinbox config
    $ # Note that you'll have to append the same `env (...)` before every `coinbox (...)` command
    
    
    $ # Or you can do this once in each session:
    $ export COINBOX_LOCALE_DIR=$VIRTUAL_ENV COINBOX_DATA_DIR=$VIRTUAL_ENV COINBOX_CONFIG_DIR=$VIRTUAL_ENV
    $ env | grep COINBOX
        COINBOX_LOCALE_DIR=/home/jkik/dev/coinbox # That's my virtualenv base directory
        COINBOX_CONFIG_DIR=/home/jkik/dev/coinbox
        COINBOX_DATA_DIR=/home/jkik/dev/coinbox
    $ coinbox config
    $ # Note that you'll have to set this every time you want to run coinbox in a session (e.g. when you open a new window in the terminal
    $ # You could add your export statements to your bash profile for example (using full paths of course) or I'll find a more convenient way to set these
  
  * The first time you run coinbox, you _might_ see "Get me to the wizard." and a blank screen. Just close it, and continue. (it's still work in progress, if you don't see it let me know so I can remove this from this document)
  
  * And if you want colors in the logs: `pip install clint`. (and set "app > log_use_colors" to true in `coinbox raw-config`).
  
  * Now configuration:
  
    $ coinbox config
    $ # Configure the database. You can just press OK for now. And say yes to everything
  
  * In case you want to use MySQL: `pip install MySQL-python` and for PostgreSQL: `pip install psycopg2`, etc.
  
  * And in case you want to help us or report a bug (which also helps us):
  
    $ coinbox raw-config
    $ # From there in the "app" tab, you can set logging level to DEBUG and direct the log to a file (easy to attach) and even give it colors (not in the file, and install clint, and on linux/mac/cygwin not windows's cmd)
  
  * And run!
  
    $ coinbox run

Okay, that's it.

There are prerequisites to these steps though, especially to build PySide.

For example, on a fresh Fedora 20 KDE system:

  * Installation prerequisites:
    * yum install python-virtualenv wget
  
  * PySide prerequisites:
    * yum install make cmake gcc gcc-c++ qt-devel phonon-devel python-devel libxml2-devel libxslt-devel qtwebkit-devel
  
  * MySQL/MariaDB prerequisites:
    * yum install mariadb-devel
    * pip install MySQL-python # (in the virtualenv)

  * PostgreSQL prerequisites:
    * yum install postgresql postgresql-devel
    * yum install postgresql-server postgresql-contrib # (optional)
    * pip install psycopg2 # (in the virtualenv)

For Debian/Ubuntu, most probably:

  * apt-get install python-virtualenv wget
  * apt-get install build-essential git cmake libqt4-dev libphonon-dev python2.7-dev libxml2-dev libxslt1-dev qtmobility-dev # for PySide (check their website)
  * apt-get install mysql-dev # (if you install MySQL-python)
  * apt-get install postgresql postgresql-client # (if you install psycopg2)

# Windows

The easiest way to install Coinbox is through the installer (which you
can find either on the website or on the Google Group or somewhere).

If you want to build the installer yourself, you'll have to set up your
own development environment and build from there.

  * Install virtualenv and a git shell
  * Create a virtualenv:
  
    virtualenv coinsetup
    cd coinsetup/
    source Scripts/activate
    
  * Install PySide, you can use pip for that (version 1.2.2 at least):
  
    pip install -U PySide

  * Install py-bcypt and Pillow (these are needed manually because they are likely to fail to install automatically on Windows):
  
    pip install Pillow
    pip install py-bcrypt-w32 # Special version for Windows, if the regular one doesn't work

  * Install core and modules (from git):
  
    pip install -e git+https://github.com/coinbox/coinbox-core.git#egg=Coinbox-pos
    
    pip install -e git+https://github.com/coinbox/coinbox-mod-base.git#egg=Coinbox-mod-base
    pip install -e git+https://github.com/coinbox/coinbox-mod-auth.git#egg=Coinbox-mod-auth
    pip install -e git+https://github.com/coinbox/coinbox-mod-config.git#egg=Coinbox-mod-config
    pip install -e git+https://github.com/coinbox/coinbox-mod-installer.git#egg=Coinbox-mod-installer
    pip install -e git+https://github.com/coinbox/coinbox-mod-currency.git#egg=Coinbox-mod-currency
    pip install -e git+https://github.com/coinbox/coinbox-mod-customer.git#egg=Coinbox-mod-customer
    pip install -e git+https://github.com/coinbox/coinbox-mod-stock.git#egg=Coinbox-mod-stock
    pip install -e git+https://github.com/coinbox/coinbox-mod-sales.git#egg=Coinbox-mod-sales
    pip install -e git+https://github.com/coinbox/coinbox-mod-taxes.git#egg=Coinbox-mod-taxes
    
  * Run Coinbox (the data/config/locale directories will be in APPDATA or similar standard Windows path by default)
  
    coinbox # This will take you through steps to set up database and some other things.

  * Install PyInstaller to build the exe and dlls before we bundle it:
  
    easy_install http://link.to/pywin32-installer.exe # Find that somewhere on the internet (sourceforge or something)
    pip install PyInstaller

  * Now, there are some issues with PyInstaller which I noticed when using it. So by the time they're fixed, here's the workaround:
  
    * Modify Lib/site-packages/PyInstaller/depend/imptracker.py; find "FIXME"; comment "setattr(parent, nm, mod)" and replace with "pass"
    
    * Modify Lib/site-packages/PyInstaller/modules.py; add after line 121:

    from pkgutil import extend_path
    self.__path__ = extend_path(self.__path__, nm)
    
    # (See: https://github.com/pyinstaller/pyinstaller/pull/28)
    
    * And an issue with ProxyTypes and/or PyInstaller: Add empty __init__.py file in Lib/site-packages/peak and Lib/site-packages/peak/util
    
    * And an issue with PyInstaller and Babel:
    
      * In PyInstaller/hooks/hook-babel.py
        * Add new hidden imports
            # ...
            hiddenimports = ["babel.dates", "babel.plural", "babel.support"]

        * Add the global.dat file to the babel/ directory
            import os
            # ...
            babel_globaldat = os.path.realpath(os.path.join(babel_localedata_dir, '..', 'global.dat'))
            # ...
            (babel_globaldat, "babel"),
            # ...

  * Ok, now we can build with PyInstaller:
  
    # You cd to src/coinbox-pos and run ...
    python setup.py bdist_pyi --clean --noconfirm --debug --db-support=MySQLdb,_mysql,psycopg2
    
    # Or, for more fine-grained control:
    # This will output in the $(current directory)/dist/
    # You can use it if you want to output to a custom directory
    pyinstaller /full/path/to/.../tools/coinbox.spec

  * Install NSIS from their website
  
  * Use either of these command to build the installer:
  
    # After cd'ing to src/coinbox-pos
    python setup.py bdist_nsis
  
    # Or, for more fine-grained control:
    # Same as before (custom directory etc.)
    /full/path/to/makensis.exe -NOCD -- /full/path/to/.../tools/installer.nsi
    
  * Note:
    Using the NSIS installer will save the config/data/locale directories in the registry,
    and any instance of Coinbox on that machine will use those. If you delete them, it'll fall
    back to AppData/Roaming or /ProgramData or AppData/Local depending on which one exists.
    (that is the default behavior if no registry keys are present)

That was long!