Installing QPixel

Method of installation

In ruby, the difference between a config file and a code file is quite blurry. Most "config" files in the config directory are just ruby files with some relatively simple code in them setting a bunch of fields. This makes ruby flexible (you can put code in your configs to make them adapt to the context!), but also a bit more challenging to understand if you are used to just yml files with keys in it. This added complexity also means that the config files are bound to change a bit more than you are used to. For bigger upgrades to QPixel you should expect to have to adapt your config files to match. If we add major dependencies, there is likely to be a so-called initialization config file which needs to be added.

Since you will be configuring your server differently than it comes "out of the box" from QPixels github repo, you need to make a decision on how you want to achieve this. The key problem is that you generally want to stay up to date with QPixel updates and changes, but that you do want potentially vastly different versions of some of the "config" files (which are actually code files). When the QPixel config files get updated, you may want to (or have to) also update your "config" files with those changes. Below we give a few different options for achieving this.

Option 1: Clone and forget (Recommended)

Clone it once, configure everything on the server directly and forget about it. You could even keep git in there to pull occasionally to pull in new changes (only recommended if you are familiar with git).

The main advantage is that it is the most straightforward to set up and configure. If you use this option, you can:

git clone https://github.com/codidact/qpixel
cd qpixel

Option 2: Create a deployment script

It is possible to create a deployment script to deal with turning a folder containing a clone of the repository into a production ready version for your server. This would involve replacing certain files with files from other locations (e.g. replace some configs with symlinks to their properly configured versions).

NOTE: There is a library called Capistrano which attempts to make this process simpler. With a Capistrano definition, it takes care of writing a script and linking the right files while allowing new files to remain unchanged. On a continuous integration server you could have it automatically deploy to your server. A capistrano definition for QPixel could look like this: base deploy configuration, server specific additional configuration. You need quite a bit of capistrano knowledge if you want to go this route, as it requires you to set up the files in the correct way. More information can be found on https://capistranorb.com/.

Option 3: Fork the repository

As an extension of option 1, you could of course also fork the repository and store your changes there. Do take care that you keep your configuration secret or that you sufficiently protect your system where you host your git repository. Perhaps you leave some changes out and combine this option with a deployment script for the last bits. The main advantage is that you can more easily deploy your setup with configs to multiple servers.

Environments

Important to know is that rails (the webserver framework used) uses so-called environments to determine how to run. By default, it will run in a development environment. The development environment has it's own separate set of libraries and settings (which means it will also run to a separate database by default). If you want to do something on production, make sure that before every session you run the following:

export RAILS_ENV=production

You can also prepend every command with RAILS_ENV=production or set this globally for the user that serves the site in its .bashrc (or .zshrc/.fishrc). In this manual we have prepended it everywhere to ensure that all commands copied from here act on the correct environment.

Finalizing

After you have made a choice for how you want to configure QPixel, we can move on to installing everything.

Installation

More detailed instructions if you need them at any point are in the installation guide.

You have two options for installing QPixel. The first option is to use the existing docker image and adapt it a bit to your needs. This means you don't have to deal with most of the setup hassle. However, the docker image in this repository was intended to set up a quick development instance, so some modifications may need to be necessary to get a performant production setup. See the installation guide for more information on using docker.

The other option is to install ruby and required libraries directly to your server. This also means you will need to run Redis and MySQL on your server (or connect to instances of these running elsewhere).

Installing system libraries

Follow the instructions in the installation guide until Install QPixel to install Ruby and the necessary system libraries.

Installing dependencies - Bundler

As most open source systems, QPixel has a lot of dependencies. QPixel users bundler, which is a package manager for ruby. Install it with:

gem install bundler

There are a few things you should know about bundler that will be important to you.

Installed to the user

By default, Bundler installs its packages to a location specific to the user. This means that you should make sure that the user which will be executing your system, is the one under which you install the packages. Otherwise, you may want to set a custom location to install your dependencies to, and point the executing user to this location.

Packages added to the path

Some dependencies come with executable commands that you can run from the command line. For example, the rails framework adds some essential commands to manage your webserver. By default these packages are added to your path such that you can execute the commands. If this is not the case (for whatever reason), you can prepend any command with bundler exec to execute it in the correct context.

Commands use the latest installed version

When you run a command from the command line without prepending bundler exec, bundler will use the LATEST VERSION of the package installed to execute the command. Even when QPixel defines an older version of the package to be used, it will pick the latest version installed. This can be relevant when you have multiple ruby systems installed on one server, or when you are attempting to rollback after a failed update. To prevent inter-version problems, prepend all commands with bundler exec to ensure that the correct version of the library is used. All commands in this tutorial have bundler exec prepended for this reason.

Finalizing

Having read all this, go ahead and install the production dependencies with:

bundle config set --local without 'development test' 
bundle install