Codidact/QPixel Installation Guide Wiki

This post aims to provide a step-by-step tutorial regarding the installation/operation of Codidact/QPixel server locally (development mode) or on a network (in production mode).
The "official" installation guide is available on GitHub.
This post is freely editable so, feel free to update/improve it!

This workflow was tested on different OS.

List of OS tested for local QPixel install, i.e. development mode (from §1 to §5 included):

OS	Version
MacOS
Debian-based	Debian 12 (and 11 on WSL2)
	Ubuntu 22.04.2 TLS (on WSL2)
Fedora	Fedora 38
Arch Linux	"2023.07.01 ISO Image"
WSL	WSL2 (Debian 11)
	WSL2 (Ubuntu 22.04.2 TLS)

Required time (from §1 to §5 included): less than 1 hour.

Currently the QPixel install failed with the following setups:

OS	Version	Failure Cause
WSL	1	Can't run the rails console
Fedora WSL2	Fedora WSL 38.0.1 by Vineel Sai, release date: 1/5/2023	Can't run the `service` command for starting the database/redis servers
Arch Linux WSL2	Arch WSL 1.0.6.0 by Vineel Sai, release date: 1/23/2023	Can't run the `service` command for starting the database/redis servers

Prerequisites
1.1. Initial prerequisites
1.2. Database server install
1.3. Ruby install
Installing QPixel
Setting up the Database
3.1. Starting the database server
3.2. Starting the redis server
3.3. Creating a new user and setting up the database
Creating an administrator account
New site setup
Running the server in production

1. Prerequisites

To run your own instance of QPixel you'll need at least:

A Linux or Mac computer (Windows Subsystem Linux, WLS^[1] is also okay, but slower; running Ruby on Windows is ultra-slow)
Some prerequisites (including Ruby and database server install) which can differ depending on the OS or platform used (e.g. WLS).

1.1. Initial prerequisites

The command lines for installing all the initial prerequisites are listed below for different OS.

Arc Linux

sudo pacman -Syyu
sudo pacman -S gcc
sudo pacman -S make
sudo pacman -S autoconf bison base-devel unixodbc
sudo pacman -S openssl
sudo pacman -S nodejs
sudo pacman -S redis
sudo pacman -S imagemagick
sudo pacman -S git
sudo pacman -S libvips

Debian-based

sudo apt install gcc
sudo apt install make
sudo apt install default-libmysqlclient-dev
sudo apt install libmagickwand-dev
sudo apt install autoconf bison build-essential libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git

Fedora

sudo dnf install gcc
sudo dnf install make
sudo dnf install vips
sudo dnf install ImageMagick-devel
sudo dnf install mysql-devel
sudo dnf install autoconf bison
sudo dnf install nodejs
sudo dnf install redis
sudo dnf install git

MacOS

xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
brew install curl
curl "https://nodejs.org/dist/latest/node-${VERSION:-$(wget -qO- https://nodejs.org/dist/latest/ | sed -nE 's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" > "$HOME/Downloads/node-latest.pkg" && sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"
brew install node

1.2. Database server install

This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).

Arch Linux

MySQL is not available on the default distribution, thus MariaDB can be installed instead [From Arch Linux wiki]:

sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql

Debian-based

On Ubuntu:

sudo apt install mysql-server

On Debian:
MySQL is not available on the default distribution, thus MariaDB can be installed instead:

sudo apt install mariadb-server

If you really want to install MySQL on Debian, you can take a look at this discussion, this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host and this official workflow).

Fedora

sudo dnf install community-mysql-server

MacOS

brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"

1.3. Ruby install

QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby gem manager like RVM or rbenv.

N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).

Unix-based

With RVM

First, you need to have curl installed:

Arch Linux:

sudo pacman -S curl

Debian-based:

sudo apt install curl

Fedora:

sudo dnf install curl

MacOS:

brew install curl

And then the rvm install:

curl -sSL https://rvm.io/mpapis.asc | gpg --import -
curl -sSL https://rvm.io/pkuczynski.asc | gpg --import -
curl -sSL https://get.rvm.io | bash -s stable

If rvm installation is complete it will tells you which command to run in order to be able to use the rvm command. In the installation outputs sample below, this command is (you need to run this command in each new opened terminal):

source /home/zetyty/.rvm/scripts/rvm

Installation outputs sample on Debian 12 (for user "zetyty"):

~$ curl -sSL https://get.rvm.io | bash -s stable
Downloading https://github.com/rvm/rvm/archive/1.29.12.tar.gz
Downloading https://github.com/rvm/rvm/releases/download/1.29.12/1.29.12.tar.gz.asc
gpg: Signature made Fri 15 Jan 2021 07:46:22 PM CET
gpg:                using RSA key 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
gpg: Good signature from "Piotr Kuczynski <[email protected]>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: 7D2B AF1C F37B 13E2 069D  6956 105B D0E7 3949 9BDB
GPG verified '/home/zetyty/.rvm/archives/rvm-1.29.12.tgz'
Installing RVM to /home/zetyty/.rvm/
    Adding rvm PATH line to /home/zetyty/.profile /home/zetyty/.mkshrc /home/zetyty/.bashrc /home/zetyty/.zshrc.
    Adding rvm loading line to /home/zetyty/.profile /home/zetyty/.bash_profile /home/zetyty/.zlogin.
Installation of RVM in /home/zetyty/.rvm/ is almost complete:

  * To start using RVM you need to run `source /home/zetyty/.rvm/scripts/rvm`
    in all your open shell windows, in rare cases you need to reopen all shell windows.
Thanks for installing RVM 🙏
Please consider donating to our open collective to help us maintain RVM.

👉  Donate: https://opencollective.com/rvm/donate

Then, install ruby:

rvm install 3.1.2

2. Installing QPixel

Once you have completed installing the prerequisites, you can download QPixel with the following command line (in this wiki post, a sample of the command outputs obtained on Debian is provided below each inline command to give an idea of what kind of results are expected):

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

Sample outputs on Debian (QPixel installed on /home directory):

~$ git clone https://github.com/codidact/qpixel
Cloning into 'qpixel'...
remote: Enumerating objects: 29058, done.
remote: Counting objects: 100% (4151/4151), done.
remote: Compressing objects: 100% (294/294), done.
remote: Total 29058 (delta 3973), reused 3886 (delta 3857), pack-reused 24907
Receiving objects: 100% (29058/29058), 8.30 MiB | 7.49 MiB/s, done.
Resolving deltas: 100% (21510/21510), done.

After downloading QPixel, you need to install all the dependencies. For that, you need to move to the qpixel directory and run (without sudo/root/admin privileges):

bundle install

Sample outputs on Debian (QPixel installed on /home directory):

~/qpixel$ bundle install
Bundler 2.3.15 is running, but your lockfile was generated with 2.4.13. Installing Bundler 2.4.13 and restarting using that version.
Fetching gem metadata from https://rubygems.org/.
Fetching bundler 2.4.13
Installing bundler 2.4.13
Fetching gem metadata from https://rubygems.org/.........
Using rake 13.0.6
Fetching minitest 5.16.3
Fetching builder 3.2.4
Fetching rack 2.2.6.4
Fetching racc 1.6.2
Fetching crass 1.0.6
Fetching nio4r 2.5.8
Fetching concurrent-ruby 1.1.10
Fetching erubi 1.11.0
Installing crass 1.0.6
Installing minitest 5.16.3
Installing builder 3.2.4
[..] # Much more install (not displayed here for brevity).
Fetching devise_saml_authenticatable 1.9.0
Installing devise_saml_authenticatable 1.9.0
Fetching sassc-rails 2.1.2
Installing sassc-rails 2.1.2
Fetching sass-rails 6.0.0
Installing sass-rails 6.0.0
Bundle complete! 55 Gemfile dependencies, 150 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.

3. Setting up the Database

3.1. Starting the database server

If the database is not already running, start it. This step depends strongly on the OS/platform used and the database server used (e.g. MySQL or MariaDB).

Arch Linux

sudo systemctl start mariadb

Debian-based

MySQL MariaDB

systemctl start mysql

service mysql start

systemctl start mariadb

service mariadb start

Fedora

systemctl enable mysqld
systemctl start mysqld

MacOS

brew services start mysql

WSL

On WSL we can't "easily" use systemctl but service instead (see this answer), it is also necessary to stop the execution of a MySQL/MariaDB server on the Windows Host and on other running WSL (because this prevents the server from being launched on the current WSL).

3.2. Starting the redis server

For the next steps you will need to have redis server started:

Arch Linux

sudo systemctl enable redis
sudo systemctl start redis

Debian-based

sudo service redis-server start

Fedora

sudo systemctl enable redis
sudo systemctl start redis

MacOS

brew services start redis

WSL

As mentionned for MariaDB/MySQL server above , on WSL we can't "easily" use systemctl but we can use service instead.

3.3. Creating a new user and setting up the database

Before we can create, set up and seed the database, we need to make sure that we have a MySQL user. Sign into the MySQL/MariaDB console with for e.g.:

sudo mysql -u root

sudo mariadb -u root

And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):

CREATE USER qpixel@localhost IDENTIFIED BY 'myPassword';
GRANT ALL ON qpixel_dev.* TO qpixel@localhost;
GRANT ALL ON qpixel_test.* TO qpixel@localhost;
GRANT ALL ON qpixel.* TO qpixel@localhost;
exit

Sample outputs on Debian with MariaDB (QPixel installed on /home/qpixel directory):

:~/qpixel$ sudo mysql -u root
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 33
Server version: 10.11.3-MariaDB-1 Debian 12

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]> CREATE USER qpixel@localhost IDENTIFIED BY 'myPassword';
Query OK, 0 rows affected (0.003 sec)

MariaDB [(none)]> GRANT ALL ON qpixel_dev.* TO qpixel@localhost;
Query OK, 0 rows affected (0.003 sec)

MariaDB [(none)]> GRANT ALL ON qpixel_test.* TO qpixel@localhost;
Query OK, 0 rows affected (0.003 sec)

MariaDB [(none)]> GRANT ALL ON qpixel.* TO qpixel@localhost;
Query OK, 0 rows affected (0.002 sec)

MariaDB [(none)]> exit
Bye

Then you'll have to tell QPixel which credentials to use. Copy the config/database.sample.yml file to config/database.yml and fill in with the same username and password to those given above with the command CREATE USER qpixel@localhost IDENTIFIED BY 'myPassword';, then in this example, the username is "qpixel" and the password is "myPassword" and the first lines of config/database.yml are (also, you will need to set the Redis connection details there too, unless you always choose the default installation options proposed above):

default: &default
  adapter: mysql2
  encoding: utf8mb4
  collation: utf8mb4_unicode_ci
  host: 127.0.0.1
  port: 3306
  # Change these credentials to match your own environment
  username: qpixel
  password: myPassword

N.B. with MariaDB, you will need to replace all occurrences of utf8mb4_0900_ai_ci with utf8mb4_unicode_ci in db/schema.rb (4 occurrences).

Now we want to create the database and the tables with:

rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate

Sample outputs on Debian (QPixel installed on /home/qpixel directory):

:~/qpixel$ rails db:create
Running via Spring preloader in process 26070
Created database 'qpixel_dev'
Created database 'qpixel_test'
:~/qpixel$ rails db:schema:load
Running via Spring preloader in process 26094
:~/qpixel$ rails r db/scripts/create_tags_path_view.rb
Running via Spring preloader in process 26103
:~/qpixel$ rails db:migrate
Running via Spring preloader in process 26108

Before we can continue and seed the data, you'll have to create the record for your (first) community. Open the Rails console with rails c and run these commands (make sure you have Redis already started because otherwise the Rails.cache.clear command will fail):

Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit

Sample outputs on Debian (QPixel installed on /home/qpixel directory):

:~/qpixel$ rails c
Running via Spring preloader in process 26118
Loading development environment (Rails 7.0.4)
3.1.2 :001 > Community.create(name: 'Dev Community', host: 'localhost:3000')
  Community Exists? (0.6ms)  SELECT 1 AS one FROM `communities` WHERE `communities`.`host` = 'localhost:3000' LIMIT 1
  Community Create (0.4ms)  INSERT INTO `communities` (`name`, `host`, `created_at`, `updated_at`, `is_fake`, `hidden`) VALUES ('Dev Community', 'localhost:3000', '2023-07-14 19:19:04', '2023-07-14 19:19:04', FALSE, FALSE)
  TRANSACTION (2.7ms)  COMMIT
 =>
#<Community:0x00007f7adba15790
 id: 1,
 name: "Dev Community",
 host: "localhost:3000",
 created_at: Fri, 14 Jul 2023 19:19:04.000000000 UTC +00:00,
 updated_at: Fri, 14 Jul 2023 19:19:04.000000000 UTC +00:00,
 is_fake: false,
 hidden: false>
3.1.2 :002 > Rails.cache.clear
 => "OK"
3.1.2 :003 > exit

After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:

rails db:seed

Sample outputs on Debian (QPixel installed on /home/qpixel directory):

:~/qpixel$ rails db:seed
Running via Spring preloader in process 26123
PostType: Created 5, skipped 0
CloseReason: Created 5, skipped 0
License: Created 5, skipped 0
TagSet: Created 2, skipped 0
PostHistoryType: Created 12, skipped 0
User: Created 1, skipped 0
Filter: Created 2, skipped 0
Ability: Created 7, skipped 0
Category: Created 2, skipped 0
PostFlagType: Created 4, skipped 0
Post: Created 15, skipped 5
ReactionType: Created 3, skipped 0
SiteSetting: Created 72, skipped 0
WarningTemplate: Created 3, skipped 0

4. Creating an administrator account

Now comes the big moment: You can start the QPixel server for the first time with (make sure you have Redis already started because otherwise your browser will display an error message):

rails s

Sample outputs on Debian (QPixel installed on /home/qpixel directory):

:~/qpixel$ rails s
=> Booting Puma
=> Rails 7.0.4 application starting in development
=> Run `bin/rails server --help` for more startup options
Puma starting in single mode...
* Puma version: 5.6.5 (ruby 3.1.2-p20) ("Birdie's Version")
*  Min threads: 5
*  Max threads: 5
*  Environment: development
*          PID: 26173
* Listening on http://127.0.0.1:3000
* Listening on http://[::1]:3000
Use Ctrl-C to stop

Open a web browser and visit your server, which should be running under http://localhost:3000.

Click on "Sign Up" button on top right corner.

Choose a email, username and password for your new administrator account.

Since the email confirmation is not configured yet, you will have to manually confirm the new user account and promote it to administrator. For that you will have to stop the current execution of the server. So, return to the console and type Ctrl-C to stop it.

Sample outputs of the server stop on Debian:

^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting

Open the rails console with rails c and run:

User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit

Sample outputs on Debian (QPixel installed on /home/qpixel directory):

:~/qpixel$ rails c
Running via Spring preloader in process 26169
Loading development environment (Rails 7.0.4)
3.1.2 :001 > User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
  User Load (0.5ms)  SELECT `users`.* FROM `users` ORDER BY `users`.`id` DESC LIMIT 1
  TRANSACTION (0.3ms)  BEGIN
  SsoProfile Load (0.8ms)  SELECT `sso_profiles`.* FROM `sso_profiles` WHERE `sso_profiles`.`user_id` = 1 LIMIT 1
  SiteSetting Load (0.5ms)  SELECT `site_settings`.* FROM `site_settings` WHERE `site_settings`.`community_id` IS NULL AND `site_settings`.`name` = 'AdminBadgeCharacter' ORDER BY IF(site_settings.community_id IS NULL, 1, 0) LIMIT 1
  SiteSetting Load (0.4ms)  SELECT `site_settings`.* FROM `site_settings` WHERE `site_settings`.`community_id` IS NULL AND `site_settings`.`name` = 'ModBadgeCharacter' ORDER BY IF(site_settings.community_id IS NULL, 1, 0) LIMIT 1
  User Update (1.1ms)  UPDATE `users` SET `users`.`updated_at` = '2023-07-14 19:23:41', `users`.`is_global_admin` = TRUE, `users`.`confirmed_at` = '2023-07-14 19:23:41' WHERE `users`.`id` = 1
  TRANSACTION (3.8ms)  COMMIT
 => true
3.1.2 :002 > exit

Now run again the rails s command, return to the web browser at http://localhost:3000 and this time you "Sign in" (click on "Sign In" button on top right corner) with your new admin user account.

5. New site setup

There's one more thing before your development server is fully up and running: the new site setup.

While being logged into your administrator account, go to http://localhost:3000/admin/setup. Review the settings (if you want; you can change them later) and click "Save and continue" to complete setting up the dev server.

✨ Your dev server is now ready.

6. Running the server in production

If you want your Codidact/Qpixel server to be running in production mode in order to be accessible on the web or on a private network then the workflow is explained on this post: How to set up a Production environment.

It seems that the rails console can't run on WSL1 (but no problem with WSL2). Also, note that the install is significantly faster with WSL2. ↩︎

posted 9 months ago

9mo ago

zetyty‭

116 reputation 7 2 21 38

Raw

Markdown

History

1 comment thread

Credits (1 comment)

Communities

Codidact/QPixel Installation Guide Wiki

Contents

1. Prerequisites

1.1. Initial prerequisites

Arc Linux

Debian-based

Fedora

MacOS

1.2. Database server install

Arch Linux

Debian-based

Fedora

MacOS

1.3. Ruby install

Unix-based

With RVM

2. Installing QPixel

3. Setting up the Database

3.1. Starting the database server

Arch Linux

Debian-based

Fedora

MacOS

WSL

3.2. Starting the redis server

Arch Linux

Debian-based

Fedora

MacOS

WSL

3.3. Creating a new user and setting up the database

4. Creating an administrator account

5. New site setup

6. Running the server in production

1 comment thread