Skip to content

Installation Guide

Jump to bottom Edit New page
William Blackerby edited this page Jan 26, 2024 · 43 revisions

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

Once you have Quepid installed, see https://github.com/o19s/quepid/blob/main/docs/operating_documentation.md on how to customize your setup.

Install Types

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.

Kubernetes Install

There is a project https://github.com/frutik/quepid-kubernete to help you install on Kubernetes.

AWS Install

Using AWS? We have some CloudFormation scripts to help you get started: https://github.com/o19s/quepid/tree/main/deployment/cloudformation.

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!

Hosting behind a context path

Set the RAILS_RELATIVE_URL_ROOT environment variable for the app container to host inside a subfolder.

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.
443 HTTPS Quepid app and core API accept HTTPS requests on this port. You can change this port in the docker-compose.yml file.

Quepid needs to match the protocol the search engine endpoint uses. If this endpoint is not using TLS/SSL then the HTTP protocol will suffice.

System requirements

Quepid requires a server with at least 1Gb memory and 1Gb swap. Server with a lot of users will require more resources.

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
  1. Download the Nginx configuration
wget https://raw.githubusercontent.com/o19s/quepid/main/nginx.conf

  1. Create a directory with mkdir .ssl for your certificates

  2. Download

wget https://raw.githubusercontent.com/o19s/quepid/main/.ssl/localhost.crt -O ./.ssl/localhost.crt

and

wget https://raw.githubusercontent.com/o19s/quepid/main/.ssl/localhost.key -O ./.ssl/localhost.key

when you are running Quepid on local machine. If you want to recreate the certificates for your localhost check https://github.com/o19s/quepid#id-like-to-test-ssl Or use your own if you want run Quepid on a server with a qualified domain name (make sure to check file names in step 5)

  1. Configure the nginx.conf file to use the name of your key that you are using. No change needed when using the key above on local machine.

  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.

  1. Run
docker-compose up -d 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. You can run sudo docker-compose logs -tf mysql to monitor it and make sure it starts cleanly!

  1. 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.

  1. Run
docker-compose up -d

to start Quepid app.

  1. Browse to your server, i.e http://localhost/ or http://yourdomain/ 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 bundle exec 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 bundle exec 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 up -d mysql
$ sleep 10  # let mysql start up!
$ docker-compose run --rm app bin/rake db:migrate
$ docker-compose up -d

Quepid with Google Analytics Tracking

If you are using Google Analytics by setting the QUEPID_GA then you need to setup Redis. See the operating_docs.md for more info.

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!!! **

Add a custom footer
Add a custom sidebar
Clone this wiki locally