-
Notifications
You must be signed in to change notification settings - Fork 1
Installation and first steps
You can either test labman_ud on your local machine (to see if it works for you or to get a taste of the features it provides), or deploy it on a server to allow other people consult data about the outcomes of your research unit's work.
To give labman_ud a try, the recommended approach is to first install it on your local machine. labman_ud is developed in django, a python web framework with a huge community behind it. Should you have any prior experience with django, trying labman_ud should not be an issue.
First, start by cloning the official repository, or download it in .zip version and extract it to your desired location.
Once downloaded, create a virtual environment with virtualenv, or with the extended tools of virtualenvwrapper. This way, we can isolate the environment for labman_ud without conflicting with the local libraries of our machines. When working on a virtual environment, its name is displayed between brackets at the beggining of the command line prompt.
Move to the project's folder with the virtual environment active, in order to install the required libraries in their desired versions in this isolated system.
These libraries and their versions are detailed in the different files within the requirements/ folder at the root level:
- base.txt: The required libraries for an out-of-the-box deployment.
- local.txt: Libraries extending the default ones for local debugging purposes.
- production.txt: Libraries extending the default ones for production environments.
The command to automatically install the dependencies is:
(virtualenv) ~/labman_ud > pip install -r requirements/[base|local|prod].txt
django provides deployment-wide variables through settings files, which can be located at /labman_ud/labman_ud/settings/. All the files there have a .py.dist extension. Copy all of them and change their extension to just .py. This way we ensure no one modifies the settings templates files, avoiding to upload sensible information to the public repository (such as passwords, absolute paths, etc).
Similar to the requirements, each file is intented for a certain installation type:
- base.py: Contains all the general settings, project-wide.
- local.py: Extends base.py with local settings.
- prod.py: Extends base.py with production settings.
To use a concrete set of settings, use the following command from the same level as the /labman_ud/manage.py file:
(virtual_env) ~/labman_ud/labman_ud/ > python manage.py command --settings=labman_ud.settings.[base|local|prod]
Important step: On the newly created settings/base.py file, edit the SECRET_KEY variable to be a unique string key. This key is internally used by django.
To start managing data, we need a database to store all the information within our research unit. For local deployment purposes, we will use the database configuration detailed in the settings/local.py file. To initialise the database, run:
(virtual_env) ~/labman_ud/labman_ud/ > python manage.py migrate --settings=labman_ud.settings.local
Now, at manage.py level, you will find a test.sqlite3 portable database file, using the SQLite3 engine.
As of django 1.7+, migrations are supported. This means that from now on, django will manage database model updates in a native way, without the need to use third party software as before (such as South, whose creator is behind the migrations inclusion).
Finally, to test everything worked as expected, we will used django's built-in development server to check the installation. Please run the following command:
(virtual_env) ~/labman_ud/labman_ud/ > python manage.py runserver --settings=labman_ud.settings.local
You should see the following message:
...
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
Now, open your favourite web browser, type the http://localhost:8000 address and you should see the welcome page with further instructions.