Bibiko / CoBL-public

Public copy of lingdb/CoBL

CoBL

The CoBL project builds on top of the LexDB that is used to serve http://ielex.mpi.nl/.

Installation

To install CoBL yourself, the following dependencies must be provided:

• A running instance of PostgreSQL complete with a database to use.
• Python 3 and pip to install the REQUIREMENTS.
• npm and Bower to install JavaScript dependencies and bootstrap.
• Grunt to minify JavaScript.
  • To install Grunt you'll likely need to have node and npm.
• git to clone the repo.

To install follow these steps:

1. Make sure you've got PostgreSQL up and running with a database to use for CoBL.

2. Get hold of a recent database dump. If you have access to the lingdb server you will find recent ones in /srv/container/postgres/backup as .bz2 files. Insert this dump into your database. If you're using the container setup you can use the lingdb/postgres container for this task.

3. Clone CoBL into a directory of your choice. Make sure to also provide potential submodules:

   git submodule init
   git submodule update --recursive
   

   This is currently used for the logo but will likely be changed in the future.

4. If you're using virtualenvwrapper, a command like this may be helpful: mkvirtualenv -p which python2.7 -r REQUIREMENTS CoBL Basically make sure you've got the REQUIREMENTS installed and are using python2.7.

5. Install bower dependencies: Inside the CoBL/static directory, run: bower install

6. Use grunt to create minified JavaScript:

   • If you don't have grunt on your system, you can use the CoBL/static/package.json to provide it for you. Calling npm install should do the trick. Inside the CoBL/static directory, run: grunt default

7. Copy CoBL/ielex/local_settings.py.dist to CoBL/ielex/local_settings.py, and edit it.

• Set DEBUG how you like it. If it is True, CoBL will serve static files itself and will not require the minified JavaScript so the grunt step isn't strictly necessary. If it is set to False, CoBL will use the minified JavaScript and will not provide static files itself. In this case an additional nginx to serve static files is a good choice.

• Set the database connection settings to something like this:

  DATABASES = {
      'default': {
          'ENGINE': 'django.db.backends.postgresql_psycopg2',
          'NAME': 'ielexdb201510',
          'USER': 'ielexuser',
          'PASSWORD': 'rieloh7aes8ooGuu5AiPoo0dahj8ooqu',
          'HOST': 'localhost',
          'PORT': '5432',
          'ATOMIC_REQUESTS': True  # Required by sqlite3 (only)
      }
  }
  

• Set SECRET_KEY to something secret.

8. Test that the database connection works and migrations are applied correctly: From CoBL/ run:
   • python2.7 manage.py syncdb
   • python2.7 manage.py migrate
9. Run the site from CoBL:
   • python2.7 manage.py runserver

Handling JavaScript

CoBL uses AMD with RequireJS to keep the JavaScript code organized.

For deployment the JavaScript code gets minified to keep the filesize small. We use a hash function to derive the name of the minified file. The resulting file will have a name like minified.af9b00f5.js which will be specific enough so that future changes will likely have different names and outdated browser caches won't be problematic.

Stylewise we make sure that our JavaScript code fits the expectations of JSHint to the extent that deployment will fail when code isn't formatted correctly.

Instead of tracking all our dependencies trough git directly or downloading them manually we use popular tools like npm and Bower. This makes it easy to upgrade dependencies to newer versions in the future and keeps the repository slim.

Getting started

1. Install node together with npm.
2. Install grunt and bower using npm:

npm install -g bower
npm install -g grunt-cli

3. Install project specific npm dependencies:

# In CoBL/static:
npm install

4. Install project specific bower dependencies:

# In CoBL/static:
bower install

5. Check and minify JavaScript with grunt:

# In CoBL/static:
grunt

You can also instruct grunt to continuously watch files for changes using grunt watch or to only use jshint using grunt jshint.

Server deployment

1. This repo was checked out to /srv/cobl

2. A cobl user was created using these commands:

   useradd -M cobl  # -M: no homedirectory created
   usermod -L cobl  # -L: no login allowed for user
   chown -R cobl.cobl /srv/cobl

   By editing /etc/passwd home of cobl was set to /srv/cobl.

3. postgresql was installed, and a user cobl owning a database cobl was created.

4. A virtualenv was created and cobl was setup using these commands:

   su cobl
   pwd  # should be /srv/cobl
   virtualenv -p `which python3` venv  # Creates virtualenv for the project
   ./venv/bin/pip install --upgrade pip
   ./venv/bin/pip install -r REQUIREMENTS
   cd static
   npm install
   nodejs ./node_modules/bower/bin/bower install
   nodejs ./node_modules/grunt-cli/bin/grunt

5. Nginx is installed and configured using the config in deployment/nginx/sites-available/cobl.

6. The unit files found in deployment are installed using deployment/placeUnitFiles.sh.

7. Updates to this setup are expected to be processed using the deployment/update.sh script, which should be executed as user cobl.