User Installation¶

Getting the Code¶

The code can be obtained from the version control system. For users, the specific instance of tendril applicable to the organization should be checked out from the locally controlled repository. This repository should be essentially read-only with a specific set of people administering the installation.

1. Create an ssh key for yourself, if you don’t already have one.

   ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
   

2. Register the key (~/.ssh/id_rsa.pub) on gitlab.

3. (Proxy) Setup ssh to use corkscrew for the git host, if necessary. Put the following into ~/.ssh/config, create the file if necessary. Your proxy credentials go into ~/.ssh/proxyauth in the format user:pass.

   Host gitlab.com
       Hostname gitlab.com
       User git
       IdentityFile ~/.ssh/id_rsa
       ProxyCommand corkscrew proxy.host port %h %p ~/.ssh/proxyauth
   

4. Get the Organization’s fork of tendril core.

   git clone git@gitlab.com:<org>/tendril.git
   

5. (Optional) Clone the submodule. (Presently only tendril-frontend-static)

   cd tendril
   git submodule update --init
   

6. Get the Organization’s instance configuration.

   git clone git@gitlab.com:<org>/tendril-instance-<org>.git ~/.tendril
   

Setting up pyenv¶

1. Install Git:

   sudo apt-get install git-core curl

2. (Proxy) Setup proxy, if any:

   export http_proxy=http://user:pass@192.168.1.254:3128
   export https_proxy=http://user:pass@192.168.1.254:3128
   export ftp_proxy=http://user:pass@192.168.1.254:3128
   

3. (Proxy) Setup corkscrew to use git through a http proxy. Proxy should be configured for github.com in ~/.ssh/config.

   Host github.com
       Hostname github.com
       User git
       IdentityFile ~/.ssh/id_rsa
       ProxyCommand corkscrew proxy.host port %h %p ~/.ssh/proxyauth
   

4. Run the pyenv installer:

   curl -L \
   https://raw.githubusercontent.com/yyuu/pyenv-installer/master/bin/pyenv-installer \
   | bash
   

5. Insert the following at the end of ~/.bashrc:

   export PYENV_ROOT="${HOME}/.pyenv"
   if [ -d "${PYENV_ROOT}" ]; then
       export PATH="${PYENV_ROOT}/bin:${PATH}"
       eval "$(pyenv init -)"
   fi
   

6. Install Build Dependencies for Python 2.7:

   sudo apt-get build-dep python2.7
   sudo apt-get install build-essential wget \
       libreadline-dev libncurses5-dev libssl1.0.0 tk8.5-dev \
       zlib1g-dev liblzma-dev
   

7. Install Python 2.7.6:

   Hint

   Python 2.7.x, where x>=6, should be fine. x<6 is untested. New features were introduced in 2.7.5, 2.7.6 that may be necessary for the scripts to run. If system python is 2.7.6 or better, pyenv isn’t strictly necessary. However, to standardize the environment in the absense of cross-version testing and intelligent installation scripts, the use of a version-specified python (as opposed to system) is recommended.

   CONFIGURE_OPTS=--enable-shared pyenv install 2.7.6
   

6. Once you’ve installed pyenv, you can use the following commands instead to setup and use your virtualenv:

   pyenv virtualenv 2.7.6 tendril
   pyenv deactivate
   pyenv activate tendril
   

Setting up virtualenv¶

1. Install virtualenv from the standard repository.

   sudo aptitude install python-virtualenv virtualenvwrapper
   

2. Create a directory for the virtual environments.

   mkdir ~/.virtualenvs
   

3. Tell virtualenvwrapper where the folder you just created is. Put it into the bashrc so that you don’t have to do it every time you restart.

   echo "export WORKON_HOME=$HOME/.virtualenvs" >> ~/.bashrc
   

   Start up a fresh shell.

4. Create a new virtualenv with the correct interpreter version. Don’t use system packages.

   mkvirtualenv tendril
   

5. mkvirtualenv leaves you with the new virtualenv active. To deactivate,

   deactivate
   

   To reactivate the virtualenv, which you should do when running the scripts in a new terminal:

   workon tendril
   

Installing the Dependencies¶

1. Install required python libraries (virtualenv should be active):

   cd /path/to/tendril/clone
   pip install -e .
   

   Hint

   You can install the package into the virtualenv or even into your system. However, due to the present volatile state of the code, you should expect a fairly continuous stream of small changes, most of which aren’t going to come with a bump in the version number. This may make upgrading the package a more involved process. This command (-e .) installs all the dependencies normally, but the tendril package itself redirects to the clone, where you can make changes which instantly propagate to the version you get when you import tendril.

   Hint

   The dependencies may require additional libraries (and their development headers) to be installed on your system. A non-exhaustive list of the libraries you should have available is :

   • libfreetype
   • libpng
   • libjpeg
   • libffi
   • libpqxx
   • libxml2
   • libxslt1

2. Install dependencies not covered by requirements.txt

   1. Install sofficehelpers:

      sofficehelpers is a collection of scripts to deal with libreoffice documents. The libreoffice python interface (uno) requires use of the python bundled into libreoffice, and therefore is kept separate from the rest of tendril. There are plenty of other (and simpler) ways to achieve the same effect, inculding a number of uno-based scripts to do this. The custom script is retained for the moment to maintain a functional base upon which additional functionality can be added on as needed. If another solution is to be used instead, appropriate changes should be made to tendril.utils.files.libreoffice.XLFile._make_csv_files() and tendril.utils.files.libreoffice.XLFile._parse_sscout().

      1. Install dependencies:

         sudo apt-get install python-uno python-pip3
         

      2. Install the sofficehelpers package from PyPi:

         pip3 install sofficehelpers
         

   2. (Optional) Install gaf 1.9.1 or the devlopment version from git. This is required for gaf export, which in turn is required to convert gschem files to pdf on a headless server. Refer to your instance specific conventions and rules to determine if using this version generally is safe.

      wget http://ftp.geda-project.org/geda-gaf/unstable/v1.9/1.9.1/geda-gaf-1.9.1.tar.gz
      tar xvzf geda-gaf-1.9.1.tar.gz
      cd geda-gaf-1.9.1
      ./configure --prefix=/opt/geda
      make
      make install
      

   3. Install pdflatex. The reference implementation assumes texlive-latex with an as-yet unspecified set of addons. The following list of ubuntu packages is a complete set which definitely contains the used latex packages, though not all of these are needed. texlive-latex-recommended is a good start.

      • texlive-latex-base
      • texlive-binaries
      • texlive-latex-recommended
      • texlive-fonts-recommended
      • texlive-font-utils
      • texlive-fonts-extra
      • texlive-generic-recommended
      • texlive-pictures
      • texlive-science
      • texlive-extra-utils
      • texlive-pstricks

   4. Install pstoedit, used to generate DXFs from gerber files.

3. Install packages required specifically for your instance. Look up your instance-specific documentation and configurations to figure out what those are.

4. Setup your repository tree. This tree need not be specially created for tendril. You can point to a folder within which all your repositories exist. The following are the constraints you should keep in mind :

   • Any folder with a configs.yaml in the correct format is assumed to be a gEDA project, and the correct folder structure around it is expected.
   • Most workflows call for specific information stored in a specific location in the repository tree, such as inventory information, for instance. These resources should mirror their location (relative to the repository root) in the canonical repository tree.
   • If you intend to generate refdocs on your computer and push them to the central instance’s refdocs filesystem, you should make sure that the repository tree you have locally exactly mirrors the organization’s repository tree.

   Beyond this, you can use whatever method or tool you desire to keep the repositories up to date. I recommend checkoutmanager.

   1. Install checkoutmanager

      pip install checkoutmanager
      

   2. Setup your ~/.checkoutmanager.cfg. Your instance may have a sample in the resources folder. If it does, you may be able to simply copy the configuration and make whatever local changes you require.

      cd ~/.tendril/resources
      cp checkoutmanager.cfg ~/.checkoutmanager.cfg
      

   3. Create the checkouts.

      checkoutmanager co
      

5. Create a local_config_overrides.py file in ~/.tendril, and add the configuration options within it which are different from the instance’s default configuration. See the local_config_overrides.py.sample for an example.

6. (Optional) Create a ‘full’ local tendril installation, detaching your copy from requiring the central tendril installation to be accessible on the network. Follow the instructions in the Instance Deployment section to :

   • Setup apache.
   • Setup the filesystems.
   • Generate your copy of refdocs.

   Warning

   Real synchronization is not implemented yet. While some parts of tendril are to safe to use in isolation, much of it is not. Use with extreme caution. The following is a non-exhaustive list of potential failures :

   • postgresql replication / synchronization is not set up. Anything that hits the database is likely to fail.
   • Filesystem synchronization is not setup. Anything that hits docstore is likely to cause trouble. refdocs and wallet are relatively safe to have a local version of the filesystem of, though you should remember that these are copies of the respective filesystem - which you will have to maintain yourself.

Updating the Core¶

cd tendril
git checkout master
git pull

Updating the Instance Folder¶

cd ~/.tendril
git checkout master
git pull