Skip to content
Snippets Groups Projects
README.md 7.66 KiB
Newer Older
Jamie Forth's avatar
Jamie Forth committed
# L2P Playability Study

Jamie Forth's avatar
Jamie Forth committed
## Outstanding tasks

Jamie Forth's avatar
Jamie Forth committed
### Sign-up/log-in
- [X] Fix subject header in login email

Jamie Forth's avatar
Jamie Forth committed
### Navigation
- [X] Attach permissions to urls
- [X] Namespace app urls (i.e. chords:index vs admin:index)
Jamie Forth's avatar
Jamie Forth committed
- [X] Add all views to breadcrumbs (and trial number for trial)
Jamie Forth's avatar
Jamie Forth committed

### Improve home screen
- [X] Edit base template to include a site name
Jamie Forth's avatar
Jamie Forth committed
- [X] Explain about tuning
- [X] Show progress numbers
Jamie Forth's avatar
Jamie Forth committed
- [X] Give suggested number or display progress bar
Jamie Forth's avatar
Jamie Forth committed
- [X] Display help automatically if no trials have been completed
Jamie Forth's avatar
Jamie Forth committed

### Profile
- [X] Merge sign-up and profile creation
- [X] Allow users to edit profile

### Trial screen
Jamie Forth's avatar
Jamie Forth committed
- [x] Add instructions pop-up
Jamie Forth's avatar
Jamie Forth committed
- [X] Save rendering preference in profile
- [X] Make sorting area responsive
Jamie Forth's avatar
Jamie Forth committed
- [X] Move rendering select button to top of page
Jamie Forth's avatar
Jamie Forth committed
- [X] Vertically stack in labelling screen
Jamie Forth's avatar
Jamie Forth committed
- [ ] Remove potential ambiguity from labelling (change chord
Jamie Forth's avatar
Jamie Forth committed
      background colour as lines are moved or snapping between divs?)
Jamie Forth's avatar
Jamie Forth committed
- [ ] show feedback of the rank order while dragging (e.g. number in
      the corner of the dragged svg)
Jamie Forth's avatar
Jamie Forth committed
- [ ] Ask test users about how many trials are reasonable.
Jamie Forth's avatar
Jamie Forth committed

### Stimuli
- [X] Remove X in guitar chords
- [x] Fix guitar chord pairs data
Jamie Forth's avatar
Jamie Forth committed
- [ ] Refine the chord sampling (take into account features, and
      possibly include more frequent chords)
- [X] Add quality control stimuli set (three trials of fixed chords)
Jamie Forth's avatar
Jamie Forth committed

Jamie Forth's avatar
Jamie Forth committed
### Admin
Jamie Forth's avatar
Jamie Forth committed
- [ ] Display a summary of individual participant responses in the
      admin interface, rather than just the raw JSON.
- [ ] Display a summary of all participant responses in the admin
      interface.
Jamie Forth's avatar
Jamie Forth committed

Jamie Forth's avatar
Jamie Forth committed
## Directory structure

Jamie Forth's avatar
Jamie Forth committed
```
├── docker-compose.override.yml
├── docker-compose.prod.yml
├── docker-compose.yml
├── LICENSE
├── nginx
│   ├── config
│   └── dockerfile
├── Pipfile
├── Pipfile.lock
├── README.md
└── web
    ├── bin
    ├── chord_study
    ├── config
    ├── dockerfile
    ├── dockerfile-prod
    ├── manage.py
    └── playability
```

Jamie Forth's avatar
Jamie Forth committed
## Requirements

* [Docker](https://www.docker.com/)
* [Docker Compose](https://docs.docker.com/compose/)

## Installation

Install Docker and Docker Compose. You may also like to install
docker-machine for remote deployment.

If Docker is installed and working, it is first necessary to build the
Jamie Forth's avatar
Jamie Forth committed
l2p/postgres image, which is needed by this project.
Jamie Forth's avatar
Jamie Forth committed


``` bash
Jamie Forth's avatar
Jamie Forth committed
# clone and build l2p-postgres image (outside of this project)
cd ..
git clone https://gitlab.doc.gold.ac.uk/l2p/l2p-postgres.git
Jamie Forth's avatar
Jamie Forth committed
cd l2p-postgres
Jamie Forth's avatar
Jamie Forth committed
docker build -t l2p/postgres .
```

Jamie Forth's avatar
Jamie Forth committed
Then build the base docker image, make migrations (database table
initialisation) and then just start the services in either development
or production mode and Docker should set up everything.

From the same directory as this README file:

``` bash
# initialise submodules
git submodule update --init
```
``` bash
# build l2p/play-web image
docker build -t l2p/play-web ./web
```

Jamie Forth's avatar
Jamie Forth committed
### Python dev environment setup (optional)

Setting up a local python virtualenv is not necessary to run the
services, but can make writing code easier.

``` bash
# From within the same directory as this README make a new virtual
# environment and install all dependencies using pipenv.

Jamie Forth's avatar
Jamie Forth committed

```

## Running the application

### Development mode

``` bash
docker-compose up
```

Jamie Forth's avatar
Jamie Forth committed
In a browser navigate to http://localhost:8000/, or the IP address of
the docker machine if you’re not on Linux.
Jamie Forth's avatar
Jamie Forth committed

To list running Docker containers run the `ps` command.

``` bash
docker ps
```

Jamie Forth's avatar
Jamie Forth committed
To manage containers use the `container` command.

``` bash
docker container ls

# or to list all containers, including stopped containers
docker container ls -a

# to clean up stopped containers
docker container prune
```

Jamie Forth's avatar
Jamie Forth committed
To shutdown all containers in this application run the `down` command.

``` bash
docker-compose down
```

To clear all database data and force re-initialisation on next start
delete the `playability_db_data` volume.

``` bash
docker volume rm playability_db_data
```
Jamie Forth's avatar
Jamie Forth committed

### Production mode

#### Swarm configuration

Production server is a Docker swarm manager.

``` bash
docker swarm init

Swarm initialized: current node (m2tixt3yz55061u2u5kg83484) is now a manager.

To add a worker to this swarm, run the following command:

    docker swarm join --token SWMTKN-1-27m53mbkzaml2ojx60zoftt4vdyysnb203nb0vmzlktviwfibl-8qxzzdg3qep1sc13s22n9oqch 158.223.53.104:2377

To add a manager to this swarm, run 'docker swarm join-token manager' and follow the instructions.
```

Create necessary Docker secrets.

``` bash
openssl rand -base64 32 | docker secret create db-root-password -
openssl rand -base64 32 | docker secret create db-l2p-password -
python -c 'import django.core.management.utils as utils; print(utils.get_random_secret_key())' | docker secret create site-secret-key -
```

``` bash
docker stack deploy -c docker-compose.yml -c docker-compose.prod.yml l2p-play
docker stack rm l2p-play
```


## Docker setup information

Currently the entire web service utilises two Docker containers in
developer mode, one for the Django application and another for the
PostgreSQL database. In production mode there is also a third
container running nginx.

### Web container

The l2p/play image is built from a dockerfile located in the ./web
project directory. It is a customisation of the official python image
containing all necessary library dependencies. It can be build and run
manually using the following command.

``` bash
docker build -t l2p/play-web ./web
```

### Database container

The l2p/postgres image is a customisation of the official postgres
image containing the init-user-db.sh script to automatically create
the l2p user at start up.

If starting the db container for the first time in development mode,
the initialisation scripts will create database user accounts
__without__ passwords.

If starting the db container for the first time in production mode,
two password files must first be created __before__ running
docker-compose/stack deploy (see [Installation](#installation)).

Database data is not stored within the database container, but is
stored in a Docker volume. This means database containers can be
started, stopped and destroyed, but the data persisted.

An l2p/postgres container can be started manually with one of the
following commands.

``` bash
# development mode
docker-compose run --rm db

# production mode
Jamie Forth's avatar
Jamie Forth committed
docker stack deploy
Jamie Forth's avatar
Jamie Forth committed
```

To access the database directly using `psql` we can either:
1. use docker exec to execute psql within the existing container

``` bash
Jamie Forth's avatar
Jamie Forth committed
docker exec -it <db_container> psql -U l2p
Jamie Forth's avatar
Jamie Forth committed
```

This option bypasses password checking (even in production) because we
are connecting from within the same container.

2. connect from localhost

``` bash
docker ps                        # find name of container
docker inspect playability_db_1  # find IP address of container
psql -h 172.19.0.2 -U postgres
```

Jamie Forth's avatar
Jamie Forth committed
## Connect to running dev containers
Jamie Forth's avatar
Jamie Forth committed

``` bash
Jamie Forth's avatar
Jamie Forth committed
docker exec -it <container> bash
Jamie Forth's avatar
Jamie Forth committed
```

### Run one-off commands in new containers

Jamie Forth's avatar
Jamie Forth committed
It may be necessary to wrap commands in `wait-for-it.sh` if the `db`
container is not already up.

Jamie Forth's avatar
Jamie Forth committed
``` bash
docker-compose run --rm web bash

docker-compose run --rm web python -m django --version

docker-compose run --rm web python manage.py showmigrations --list

Jamie Forth's avatar
Jamie Forth committed
docker-compose run --rm web ./bin/wait-for-it.sh db:5432 -- python manage.py makemigrations chord_study

docker-compose run --rm web ./bin/wait-for-it.sh db:5432 -- python manage.py migrate
```

## Database admin
Jamie Forth's avatar
Jamie Forth committed

Jamie Forth's avatar
Jamie Forth committed
``` bash
docker exec -it <db_container> bash
Jamie Forth's avatar
Jamie Forth committed
```

Jamie Forth's avatar
Jamie Forth committed
``` bash
docker exec -it <db_container> psql -U l2p
```
Jamie Forth's avatar
Jamie Forth committed

``` bash
Jamie Forth's avatar
Jamie Forth committed
# Production only.
docker exec -it <db_container> backups
Jamie Forth's avatar
Jamie Forth committed
```

``` bash
Jamie Forth's avatar
Jamie Forth committed
# Production only.
docker exec -it <db_container> backup
Jamie Forth's avatar
Jamie Forth committed
```