Installation Guide

This page is for folks who don't want to use the hosted Quepid at http://www.quepid.com/.

This page is a work in progress, and is meant for use with Quepid 6.2.0 release and newer. Feedback appreciated!

Heroku Install

The hosted version of Quepid runs on Heroku's infrastructure. The app.json file is provided to for you to deploy your own copy of Quepid on Heroku, and lets you customize your setup.

Docker Compose based Install

Quepid can be deployed as several Docker containers. You can therefore deploy it on any Linux distribution that supports Docker. The target host requires Docker and Docker Compose to be installed.

Software

The following table lists the software versions that must be installed on the target host.

Software	Version	Description
Docker engine	version 17.06.0-ce+ or higher	For installation instructions, see docker engine doc
Docker Compose	version 1.18.0 or higher	For installation instructions, see docker compose doc

Database

Quepid is only tested with MySQL, and specifically, with the version of MySQL in the docker-compose.yml file. People have used AWS RDS as the database backend successfully with Quepid instead of the local MySQL. It would be a significant effort to having the CI/CD processes to support Postgres and other databases, however the community would welcome that!

Network ports

Quepid requires that the following ports be open on the target host.

Port	Protocol	Description
80	HTTP	Quepid app and core API accept HTTP requests on this port. You can change this port in the docker-compose.yml file.

Installation Procedure

The installation procedure involves the following steps:

1. Download the production docker-compose.prod.yml template file via wget https://raw.githubusercontent.com/o19s/quepid/master/docker-compose.prod.yml -O docker-compose.yml
2. Configure the docker-compose.yml file to customize the settings for your production environment. Learn more by reading Operating Documentation.
3. Run docker-compose pull to download all images required.
4. Run docker-compose up -d redis mysql to start the dependencies. Count to 10 to give them a chance to fire up! If you're running on Windows make sure to share the volume drive in docker settings.
5. Run docker-compose run --rm app bin/rake db:setup to setup an empty database with the schema. If you get a connection error, wait a few more seconds to make sure MySql has started and try again.
6. Run docker-compose up -d to start Quepid app.
7. Browse to your server, i.e http://yourserver/ and after around 30 seconds on the first request you will be taken to the login screen.

Create your Administrator user

Various functions of Quepid, such as setting default scorers, or looking at user data are only available to users who are marked as Administrator. When you first set up Quepid you don't have a Administrator. To create a new administrator from scratch run:

docker-compose run app thor user:create -a admin@example.com Administrator mysuperstrongpassword

This user then can grant administrator privileges through the Quepid app.

If you have an existing account that you want to make administrator, run:

docker-compose run app thor user:grant_administrator admin@example.com 

Managing Quepid Lifecycle

You can use docker-compose to manage the lifecycle of Quepid. Some useful commands are listed below. You must run the commands in the same directory as docker-compose.prod.yml.

Stop Quepid:

$ docker-compose stop
Stopping quepid_prod_app   ... done
Stopping quepid_prod_db    ... done
Stopping quepid_prod_redis ... done

Restart Quepid after Stopping:

$ docker-compose start
Starting mysql ... done
Starting redis ... done
Starting app   ... done

Updating Quepid

To update Quepid, stop the existing Quepid instance, pull the latest image, and review the current docker-compose.prod.yml file in Github compared to your local docker-compose.yml. Then run some database migration tasks:

$ docker-compose down
$ docker-compose pull
$ vim docker-compose.yml
$ docker-compose run --rm app bin/rake db:migrate
$ docker-compose run --rm app bin/rake db:seed
$ docker-compose up -d

Quepid using WSL and Docker on Windows 10

It is possible to run this setup, but it is important to shutdown docker properly before exiting WSl shell using:

$ docker-compose down

In case you forgot to shutdown properly, the Quepid DB has been deleted. To reinstall the DB run:

$ docker-compose run --rm app bin/rake db:setup
$ docker-compose up -d

Quepid using MacOS on Apple Silicon M1 Chip

In case you present problems starting Quepid's Docker containers on M1, please run the following command on your Mac

$ softwareupdate --install-rosetta

Once you restart your computer modify the docker-compose.prod.yml file:

• Switch MySQL database image to MariaDB on quepid_db service section

services:
  mysql:
    container_name: quepid_db
    image: mariadb
    ports:
      - 3306:3306
    environment:
      - MYSQL_ROOT_PASSWORD=password

• Add platform emulation field platform: linux/amd64 on quepid_app service:

app:
    container_name: quepid_app
    platform: linux/amd64
    build:
      context: .
      dockerfile: Dockerfile.dev
    env_file:
      - .env
    ...

For reference: https://docs.docker.com/desktop/mac/apple-silicon/

Other Commands

Stop Quepid AND remove Quepid's database files on the file system:

$ docker-compose down
$ rm -r ./volumes/mysql_data

** Warning you will lose your data!!! **