-
Notifications
You must be signed in to change notification settings - Fork 101
Installation Guide
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.
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.
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.
There is a project https://github.com/frutik/quepid-kubernetes to help you install on Kubernetes.
Using AWS? We have some CloudFormation scripts to help you get started: https://github.com/o19s/quepid/tree/main/deployment/cloudformation.
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!
Set the RAILS_RELATIVE_URL_ROOT environment variable for the app container to host inside a subfolder.
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.
Quepid requires a server with at least 1Gb memory and 1Gb swap. Server with a lot of users will require more resources.
The installation procedure involves the following steps:
- Download the production
docker-compose.prod.ymltemplate file via
wget https://raw.githubusercontent.com/o19s/quepid/master/docker-compose.prod.yml -O docker-compose.yml
- Download the Nginx configuration
wget https://raw.githubusercontent.com/o19s/quepid/main/nginx.conf
-
Create a directory with
mkdir .sslfor your certificates -
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)
-
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.
-
Configure the docker-compose.yml file to customize the settings for your production environment. Learn more by reading Operating Documentation.
-
Run
docker-compose pull
to download all images required.
- 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!
- 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.
- Run
docker-compose up -d
to start Quepid app.
- 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.
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 [email protected] 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 [email protected]
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.
$ docker-compose stop
Stopping quepid_prod_app ... done
Stopping quepid_prod_db ... done
Stopping quepid_prod_redis ... done$ docker-compose start
Starting mysql ... done
Starting redis ... done
Starting app ... doneTo 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 -dIf you are using Google Analytics by setting the QUEPID_GA then you need to setup Redis. See the operating_docs.md for more info.
It is possible to run this setup, but it is important to shutdown docker properly before exiting WSl shell using:
$ docker-compose downIn 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 -dIn case you present problems starting Quepid's Docker containers on M1, please run the following command on your Mac
$ softwareupdate --install-rosettaOnce 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/amd64on 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/
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!!! **