Post History

Q&A Codidact/QPixel Installation Guide

posted 10mo ago by zetyty‭ · edited 9mo ago by zetyty‭

Wiki guide installation development production

#20: Post edited by

zetyty‭ · 2023-08-05T22:12:21Z (9 months ago)
Remove the credits settence (moved into comment threads)

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* **List of OS tested for local QPixel install**, i.e. development mode (from §1 to §5 included):
<section class='notice is-success'>
| 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) |
</section>
Required time (from §1 to §5 included): less than 1 hour.
* **Currently the QPixel install failed with the following setups:**
<section class='notice is-danger'>
| OS | Version | Failure Cause |
| - | - | - |
| WSL | 1 | Can't run the rails console |
| Fedora WSL2 | [Fedora WSL 38.0.1 by Vineel Sai](https://github.com/VSWSL/Fedora-WSL), 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](https://github.com/VSWSL/Arch-WSL), release date: 1/23/2023 | Can't run the `service` command for starting the database/redis servers |
</section>
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
<details>
<summary>
First, you need to have `curl` installed:
</summary>
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
brew install curl
```
</details>
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
~~***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*~~
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* **List of OS tested for local QPixel install**, i.e. development mode (from §1 to §5 included):
<section class='notice is-success'>
| 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) |
</section>
Required time (from §1 to §5 included): less than 1 hour.
* **Currently the QPixel install failed with the following setups:**
<section class='notice is-danger'>
| OS | Version | Failure Cause |
| - | - | - |
| WSL | 1 | Can't run the rails console |
| Fedora WSL2 | [Fedora WSL 38.0.1 by Vineel Sai](https://github.com/VSWSL/Fedora-WSL), 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](https://github.com/VSWSL/Arch-WSL), release date: 1/23/2023 | Can't run the `service` command for starting the database/redis servers |
</section>
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
<details>
<summary>
First, you need to have `curl` installed:
</summary>
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
brew install curl
```
</details>
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
[^1]: 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.

#19: Post edited by

zetyty‭ · 2023-08-05T21:37:58Z (9 months ago)
add list of failed install in some OS

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
<details>
<summary>
First, you need to have `curl` installed:
</summary>
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
brew install curl
```
</details>
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* **List of OS tested for local QPixel install**, i.e. development mode (from §1 to §5 included):
<section class='notice is-success'>
| 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) |
</section>
Required time (from §1 to §5 included): less than 1 hour.
* **Currently the QPixel install failed with the following setups:**
<section class='notice is-danger'>
| OS | Version | Failure Cause |
| - | - | - |
| WSL | 1 | Can't run the rails console |
| Fedora WSL2 | [Fedora WSL 38.0.1 by Vineel Sai](https://github.com/VSWSL/Fedora-WSL), 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](https://github.com/VSWSL/Arch-WSL), release date: 1/23/2023 | Can't run the `service` command for starting the database/redis servers |
</section>
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
<details>
<summary>
First, you need to have `curl` installed:
</summary>
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
brew install curl
```
</details>
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#18: Post edited by

zetyty‭ · 2023-08-05T20:29:02Z (9 months ago)
add nested summary/details section for curl install

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
~~First you have to install `curl`:~~
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
<details>
<summary>
First, you need to have `curl` installed:
</summary>
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
brew install curl
```
</details>
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#17: Post edited by

zetyty‭ · 2023-08-01T20:39:08Z (9 months ago)
add hyperlink to 3.1 from 3.2

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
~~As mentionned for MariaDB/MySQL server above, on WSL we can't "easily" use `systemctl` but we can use `service` instead.~~
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for [MariaDB/MySQL server above](#starting-the-database-server) , on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#16: Post edited by

zetyty‭ · 2023-08-01T20:36:59Z (9 months ago)
add redis start command lines

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
~~3.1. [Starting the database server](#starting-the-database-server)~~
~~3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)~~
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
~~<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>~~
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Starting the redis server](#starting-the-redis-server)
3.3. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't "easily" use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="starting-the-redis-server">3.2. Starting the redis server</h2>
For the next steps you will need to have redis server started:
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo service redis-server start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo systemctl enable redis
sudo systemctl start redis
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start redis
```
</details>
<details>
<summary>
### WSL
</summary>
As mentionned for MariaDB/MySQL server above, on WSL we can't "easily" use `systemctl` but we can use `service` instead.
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.3. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
or
```bash
sudo mariadb -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#15: Post edited by

zetyty‭ · 2023-07-31T21:10:14Z (10 months ago)
update database install

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
~~MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:~~
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
~~[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]~~
```bash
~~sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql~~
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
MySQL is not available on the default distribution, thus MariaDB can be installed instead
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]:
```bash
sudo pacman -S mariadb
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#14: Post edited by

zetyty‭ · 2023-07-31T21:05:59Z (10 months ago)
add curl install for different OS

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
~~* **With RVM**~~
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
~~And then:~~
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
#### **With RVM**
First you have to install `curl`:
* Arch Linux:
```bash
sudo pacman -S curl
```
* Debian-based:
```bash
sudo apt install curl
```
* Fedora:
```bash
sudo dnf install curl
```
* MacOS:
```bash
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 "/"
```
And then the rvm install:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#13: Post edited by

zetyty‭ · 2023-07-31T20:56:18Z (10 months ago)
OS in alphabetic order

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
~~bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"~~
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### Arch Linux
</summary>
```bash
~~sudo pacman -S mariadb~~
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### Arch Linux
</summary>
~~[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]~~
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### Arch Linux
</summary>
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#12: Post edited by

zetyty‭ · 2023-07-31T20:35:00Z (10 months ago)
typo + change Arch Version in list

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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" |~~
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
Required time (from §1 to §5 included): less than 1 hour.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
~~xcode-select --install~~
brew install bison
~~brew install redis~~
~~brew install imagemagick~~
# NodeJS install
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~~
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### Arc Linux
</summary>
```bash
~~sudo pacman -Syyu~~
~~sudo pacman -Sy gcc~~
~~sudo pacman -Sy make~~
sudo pacman -Sy autoconf bison base-devel unixodbc
sudo pacman -Sy openssl
sudo pacman -Sy nodejs
~~sudo pacman -Sy redis~~
~~sudo pacman -Sy imagemagick~~
sudo pacman -Sy git
~~sudo pacman -Sy libvips~~
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### Arch Linux
</summary>
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
~~***Credit:** this post is was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*~~
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### Arc Linux
</summary>
```bash
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### Arch Linux
</summary>
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#11: Post edited by

zetyty‭ · 2023-07-29T07:36:17Z (10 months ago)
Add Arch Linux prerequisites

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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 |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
Required time (from §1 to §5 included): less than 1 hour.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post is was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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" |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
Required time (from §1 to §5 included): less than 1 hour.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<details>
<summary>
### Arc Linux
</summary>
```bash
sudo pacman -Syyu
sudo pacman -Sy gcc
sudo pacman -Sy make
sudo pacman -Sy autoconf bison base-devel unixodbc
sudo pacman -Sy openssl
sudo pacman -Sy nodejs
sudo pacman -Sy redis
sudo pacman -Sy imagemagick
sudo pacman -Sy git
sudo pacman -Sy libvips
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<details>
<summary>
### Arch Linux
</summary>
```bash
sudo pacman -S mariadb
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### Arch Linux
</summary>
[[From Arch Linux wiki](https://wiki.archlinux.org/title/MariaDB)]
```bash
sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
sudo systemctl start mariadb
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post is was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#10: Post edited by

zetyty‭ · 2023-07-23T20:44:27Z (10 months ago)
remove sudo from service command lines for MySQL and MariaDB start on Debian-based systems

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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 |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
Required time (from §1 to §5 included): less than 1 hour.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
~~sudo systemctl start mysql~~
```
or
```bash
~~sudo service mysql start~~
```
</td>
<td>
```bash
~~sudo systemctl start mariadb~~
```
or
```bash
~~sudo service mariadb start~~
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post is was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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 |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
Required time (from §1 to §5 included): less than 1 hour.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
systemctl start mysql
```
or
```bash
service mysql start
```
</td>
<td>
```bash
systemctl start mariadb
```
or
```bash
service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post is was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#9: Post edited by

zetyty‭ · 2023-07-23T20:27:33Z (10 months ago)
Update Fedora command line + improve Ruby install section + redis start before Rails.cache.clear

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
~~This workflow was tested on some OS.~~
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
~~| Fedora | |~~
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl~~
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
~~dnf install vips~~
~~dnf install ImageMagick-devel~~
~~dnf install mysql-devel~~
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
~~On Ubuntu:~~
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
~~dnf install community-mysql-server~~
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
~~### Debian-based~~
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
~~After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:~~
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
~~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:~~
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
~~Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):~~
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
~~***Credit:** this question was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*~~
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on different OS.
</summary>
* 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 |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
Required time (from §1 to §5 included): less than 1 hour.
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
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
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
* **On Ubuntu:**
```bash
sudo apt install mysql-server
```
* **On Debian:**
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
sudo dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Unix-based
</summary>
* **With RVM**
First you have to install `curl` (e.g. `sudo apt install curl` on Debian-based systems).
And then:
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
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](https://collab.codidact.org/posts/288973/288996#answer-288996)):
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise the `Rails.cache.clear` command will fail):
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([make sure you have Redis already started](https://collab.codidact.org/posts/285407/285409#answer-285409) because otherwise your browser will display an error message):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this post is was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#8: Post edited by

zetyty‭ · 2023-07-22T05:50:13Z (10 months ago)
add luap42 credit

Copy Link

Raw

Markdown

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on some OS.
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
[^1]: 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.

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on some OS.
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
***Credit:** this question was initially written by luap42 in [this answer](https://collab.codidact.org/posts/280451/280452#answer-280452).*
[^1]: 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.

#7: Post edited by

zetyty‭ · 2023-07-22T05:45:27Z (10 months ago)
remove the top quoted message + change title for hypperlinks

Copy Link

Raw

Markdown

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on the following OS:
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
~~<div id="prerequisites">~~
~~# 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).
~~<div id="initial-prerequisites">~~
~~## 1.1. Initial prerequisites.~~
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
~~## 1.2. Database server install~~
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
~~## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
~~</div>~~
~~</div>~~
~~<div id="installing-qpixel">~~
~~# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
~~# 3. Setting up the Database~~
~~<div id="starting-the-database-server">~~
~~## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
~~</div>~~
~~<div id="creating-a-new-user-and-setting-up-the-database">~~
~~## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
~~<div id="creating-an-administrator-account">~~
~~# 4. Creating an administrator account~~
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
~~</div>~~
~~<div id="new-site-setup">~~
~~# 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.
~~</div>~~
~~<div id="running-the-server-in-production">~~
~~# 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](https://collab.codidact.org/posts/287738).
~~</div>~~
~~[^1]: 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.~~

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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on some OS.
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<h1 id="prerequisites">1. Prerequisites</h1>
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).
<h2 id="initial-prerequisites">1.1. Initial prerequisites</h2>
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
<h2 id="database-server-install">1.2. Database server install</h2>
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
<h2 id="ruby-install">1.3. Ruby install</h2>
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend a Ruby `gem` manager like [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
<h1 id="installing-qpixel">2. Installing QPixel</h1>
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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
<h1 id="setting-up-the-database">3. Setting up the Database</h1>
<h2 id="starting-the-database-server">3.1. Starting the database server</h2>
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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
<h2 id="creating-a-new-user-and-setting-up-the-database">3.2. Creating a new user and setting up the database</h2>
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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
<h1 id="creating-an-administrator-account">4. Creating an administrator account</h1>
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<h1 id="new-site-setup">5. New site setup</h1>
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.
<h1 id="running-the-server-in-production">6. Running the server in production</h1>
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](https://collab.codidact.org/posts/287738).
[^1]: 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.

#6: Post edited by

zetyty‭ · 2023-07-21T09:46:05Z (10 months ago)
update link to §3.2

Copy Link

Raw

Markdown

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on the following OS:
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
~~3.2. [Create a new user and setting up the database](#create-a-new-user-and-setting-up-the-database)~~
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
~~<div id="create-a-new-user-and-setting-up-the-database">~~
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on the following OS:
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Creating a new user and setting up the database](#creating-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
<div id="creating-a-new-user-and-setting-up-the-database">
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

#5: Post edited by

zetyty‭ · 2023-07-21T05:38:36Z (10 months ago)
Add MySQL for Ubuntu + Add OS tested table at begining

Copy Link

Raw

Markdown

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Create a new user and setting up the database](#create-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
<div id="create-a-new-user-and-setting-up-the-database">
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
<details>
<summary>
This workflow was tested on the following OS:
</summary>
| OS | Version |
| - | - |
| MacOS | |
| Debian-based | Debian 12 (and 11 on WSL2) |
| | Ubuntu 22.04.2 TLS (on WSL2) |
| Fedora | |
| WSL | WSL2 (Debian 11) |
| | WSL2 (Ubuntu 22.04.2 TLS) |
</details>
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Create a new user and setting up the database](#create-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
On Ubuntu:
```bash
sudo apt install mysql-server
```
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
<table>
<tr>
<td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td>
```bash
sudo systemctl start mysql
```
or
```bash
sudo service mysql start
```
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
</table>
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
<div id="create-a-new-user-and-setting-up-the-database">
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

#4: Post edited by

zetyty‭ · 2023-07-20T21:08:42Z (10 months ago)
typo

Copy Link

Raw

Markdown

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Create a new user and setting up the database](#create-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
<div id="create-a-new-user-and-setting-up-the-database">
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
~~Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):~~
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
~~Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):~~
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
~~Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):~~
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
~~Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):~~
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
~~Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):~~
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Create a new user and setting up the database](#create-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
<div id="create-a-new-user-and-setting-up-the-database">
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

#3: Post edited by

zetyty‭ · 2023-07-20T20:42:00Z (10 months ago)
version 3: OS specificities listed with subheaders and details/summary sections + full paraphrase of lup42 answer

Copy Link

Raw

Markdown

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
~~1.1. [Initial prerequisites](#initial-prerequisites)~~
~~1.2. [Database server install](#database-server-install)~~
~~1.3. [Ruby install](#ruby-install)~~
2. [Installing QPixel](#installing-qpixel)
~~3. [Setting up the Database](#setting-up-the-database)~~
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 1. Prerequisites
To run your own instance of QPixel you'll need at least:
* A Linux or Mac computer (Windows WSL2 is also okay, but slower; running Ruby on Windows is ultra-slow)
Also you'll need some prerequisites (including Ruby and database server install) which can differ depending on the OS or platform used (ex. Windows Subsystem Linux, WLS).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
~~**Table 1** below gives some links to dedicated posts for specific platform.~~
~~<table>~~
~~<tr>~~
~~<td> OS </td> <td> Version tested </td> <td> Inline commands samples to install initial prerequisites</td>~~
~~</tr>~~
~~<tr>~~
~~<td> MacOS </td> <td> </td>~~
~~<td>~~
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</td>
</tr>
<tr>
<td> Debian-based </td>
~~<td>~~
~~- Debian 12 (and 11 on WSL2)~~
~~- Ubuntu 22.04.2 TLS (on WSL2)~~
~~</td>~~
~~<td>~~
```bash
sudo apt install gcc
sudo apt install make
~~sudo apt install default-libmysqlclient-dev # libmysqlclient-dev not disponible on Debian~~
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
~~</td>~~
~~</tr>~~
~~<tr>~~
~~<td> Fedora </td>~~
~~<td>~~
~~</td>~~
~~<td>~~
~~```bash~~
~~#dnf install gcc~~
~~#dnf install make~~
~~#dnf install libmagickwand-dev~~
~~#dnf install autoconf bison build-essential libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev~~
~~#dnf install curl~~
~~#dnf install nodejs~~
~~#dnf install redis~~
~~#dnf install git~~
~~dnf install vips # is it really necessary?~~
dnf install ImageMagick-devel
dnf install mysql-devel
```
</td>
~~</tr>~~
</table>
</div>
<div id="database-server-install">
## 1.2. Database server install
~~<table>~~
~~<tr>~~
~~<td> OS </td> <td> MySQL </td> <td> MariaDB </td>~~
~~</tr>~~
~~<tr>~~
<td> MacOS </td>
~~<td>~~
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</td>
~~<td> </td>~~
~~</tr>~~
~~<tr>~~
~~<td> Debian-based </td>~~
<td>
~~MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead[^2]~~
~~</td>~~
~~<td>~~
```bash
sudo apt install mariadb-server
```
~~</td>~~
~~</tr>~~
~~<tr>~~
<td> Fedora </td>
~~<td>~~
```bash
dnf install community-mysql-server
```
</td>
~~<td>~~
~~</td>~~
~~</tr>~~
</table>
</div>
<div id="ruby-install">
## 1.3. Ruby install
~~QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).~~
~~QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).~~
<details>
<summary>
Example with RVM on Debian:
</summary>
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
~~## 3.1. Start 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).
**Table 2** below gives some command line exemple to start your database server depending on the OS.
~~<table>~~
~~<tr>~~
~~<td> OS </td> <td> MySQL </td> <td> MariaDB </td>~~
~~</tr>~~
<tr>
~~<td> MacOS </td>~~
<td>
```bash
brew services start mysql
```
~~</td>~~
<td> </td>
~~</tr>~~
~~<tr>~~
<td> Debian-based </td>
~~<td>~~
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
~~</td>~~
</tr>
~~<tr>~~
<td> Fedora </td>
~~<td>~~
```bash
systemctl enable mysqld
systemctl start mysqld
```
</td>
~~<td>~~
~~</td>~~
~~</tr>~~
</table>
**N.B. On WSL** we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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].
~~## 3.2. Create a new user and set 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
~~[^1]: It seems taht the rails console can't run on WSL1 (but I got no problem with WSL2). Also, note that the install is significantly faster with WSL2.~~
[^2]: If you really want to install MySQL, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
[^3]: To stop MySQL on Windows: ppen a on command prompt and run `net stop MySQL80`. On other running WSL, (i) you can stop MySQL/MariaDB server on other WSL or (ii) you can stop the running WSL by opening a PowerShell and run `wsl -t DISTRO-NAME` - you can find the list of all `DISTRO-NAME` installed and their status (running/stopped) with `wsl -l -v`.

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
3.1. [Starting the database server](#starting-the-database-server)
3.2. [Create a new user and setting up the database](#create-a-new-user-and-setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 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).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
The command lines for installing all the initial prerequisites are listed below for different OS.
<details>
<summary>
### MacOS
</summary>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install vips
dnf install ImageMagick-devel
dnf install mysql-devel
```
</details>
</div>
<div id="database-server-install">
## 1.2. Database server install
This workflow use MySQL or MariaDB server, the installation steps can differ depending on the OS (some examples below).
<details>
<summary>
### MacOS
</summary>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</details>
<details>
<summary>
### Debian-based
</summary>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead:
```bash
sudo apt install mariadb-server
```
If you really want to install MySQL on Debian, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
</details>
<details>
<summary>
### Fedora
</summary>
```bash
dnf install community-mysql-server
```
</details>
</div>
<div id="ruby-install">
## 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](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
N.B. QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
### Debian-based
</summary>
#### With RVM
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
<div id="starting-the-database-server">
## 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).
<details>
<summary>
### MacOS
</summary>
```bash
brew services start mysql
```
</details>
<details>
<summary>
### Debian-based
</summary>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</details>
<details>
<summary>
### Fedora
</summary>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</details>
<details>
<summary>
### WSL
</summary>
On WSL we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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).
</details>
</div>
<div id="create-a-new-user-and-setting-up-the-database">
## 3.2. 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: 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.

#2: Post edited by

zetyty‭ · 2023-07-20T18:51:23Z (10 months ago)
Typo on top message

Copy Link

Raw

Markdown

> **Please don't edit or comment this post (until with message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 1. Prerequisites
To run your own instance of QPixel you'll need at least:
* A Linux or Mac computer (Windows WSL2 is also okay, but slower; running Ruby on Windows is ultra-slow)
Also you'll need some prerequisites (including Ruby and database server install) which can differ depending on the OS or platform used (ex. Windows Subsystem Linux, WLS).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
**Table 1** below gives some links to dedicated posts for specific platform.
<table>
<tr>
<td> OS </td> <td> Version tested </td> <td> Inline commands samples to install initial prerequisites</td>
</tr>
<tr>
<td> MacOS </td> <td> </td>
<td>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</td>
</tr>
<tr>
<td> Debian-based </td>
<td>
- Debian 12 (and 11 on WSL2)
- Ubuntu 22.04.2 TLS (on WSL2)
</td>
<td>
```bash
sudo apt install gcc
sudo apt install make
sudo apt install default-libmysqlclient-dev # libmysqlclient-dev not disponible on Debian
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
</td>
<td>
```bash
#dnf install gcc
#dnf install make
#dnf install libmagickwand-dev
#dnf install autoconf bison build-essential libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev
#dnf install curl
#dnf install nodejs
#dnf install redis
#dnf install git
dnf install vips # is it really necessary?
dnf install ImageMagick-devel
dnf install mysql-devel
```
</td>
</tr>
</table>
</div>
<div id="database-server-install">
## 1.2. Database server install
<table>
<tr>
<td> OS </td> <td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td> MacOS </td>
<td>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</td>
<td> </td>
</tr>
<tr>
<td> Debian-based </td>
<td>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead[^2]
</td>
<td>
```bash
sudo apt install mariadb-server
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
```bash
dnf install community-mysql-server
```
</td>
<td>
</td>
</tr>
</table>
</div>
<div id="ruby-install">
## 1.3. Ruby install
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
Example with RVM on Debian:
</summary>
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
## 3.1. Start 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).
**Table 2** below gives some command line exemple to start your database server depending on the OS.
<table>
<tr>
<td> OS </td> <td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td> MacOS </td>
<td>
```bash
brew services start mysql
```
</td>
<td> </td>
</tr>
<tr>
<td> Debian-based </td>
<td>
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</td>
<td>
</td>
</tr>
</table>
**N.B. On WSL** we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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].
## 3.2. Create a new user and set 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: It seems taht the rails console can't run on WSL1 (but I got no problem with WSL2). Also, note that the install is significantly faster with WSL2.
[^2]: If you really want to install MySQL, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
[^3]: To stop MySQL on Windows: ppen a on command prompt and run `net stop MySQL80`. On other running WSL, (i) you can stop MySQL/MariaDB server on other WSL or (ii) you can stop the running WSL by opening a PowerShell and run `wsl -t DISTRO-NAME` - you can find the list of all `DISTRO-NAME` installed and their status (running/stopped) with `wsl -l -v`.

> **Please don't edit or comment this post (until this message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 1. Prerequisites
To run your own instance of QPixel you'll need at least:
* A Linux or Mac computer (Windows WSL2 is also okay, but slower; running Ruby on Windows is ultra-slow)
Also you'll need some prerequisites (including Ruby and database server install) which can differ depending on the OS or platform used (ex. Windows Subsystem Linux, WLS).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
**Table 1** below gives some links to dedicated posts for specific platform.
<table>
<tr>
<td> OS </td> <td> Version tested </td> <td> Inline commands samples to install initial prerequisites</td>
</tr>
<tr>
<td> MacOS </td> <td> </td>
<td>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</td>
</tr>
<tr>
<td> Debian-based </td>
<td>
- Debian 12 (and 11 on WSL2)
- Ubuntu 22.04.2 TLS (on WSL2)
</td>
<td>
```bash
sudo apt install gcc
sudo apt install make
sudo apt install default-libmysqlclient-dev # libmysqlclient-dev not disponible on Debian
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
</td>
<td>
```bash
#dnf install gcc
#dnf install make
#dnf install libmagickwand-dev
#dnf install autoconf bison build-essential libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev
#dnf install curl
#dnf install nodejs
#dnf install redis
#dnf install git
dnf install vips # is it really necessary?
dnf install ImageMagick-devel
dnf install mysql-devel
```
</td>
</tr>
</table>
</div>
<div id="database-server-install">
## 1.2. Database server install
<table>
<tr>
<td> OS </td> <td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td> MacOS </td>
<td>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</td>
<td> </td>
</tr>
<tr>
<td> Debian-based </td>
<td>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead[^2]
</td>
<td>
```bash
sudo apt install mariadb-server
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
```bash
dnf install community-mysql-server
```
</td>
<td>
</td>
</tr>
</table>
</div>
<div id="ruby-install">
## 1.3. Ruby install
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
Example with RVM on Debian:
</summary>
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
## 3.1. Start 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).
**Table 2** below gives some command line exemple to start your database server depending on the OS.
<table>
<tr>
<td> OS </td> <td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td> MacOS </td>
<td>
```bash
brew services start mysql
```
</td>
<td> </td>
</tr>
<tr>
<td> Debian-based </td>
<td>
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</td>
<td>
</td>
</tr>
</table>
**N.B. On WSL** we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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].
## 3.2. Create a new user and set 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: It seems taht the rails console can't run on WSL1 (but I got no problem with WSL2). Also, note that the install is significantly faster with WSL2.
[^2]: If you really want to install MySQL, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
[^3]: To stop MySQL on Windows: ppen a on command prompt and run `net stop MySQL80`. On other running WSL, (i) you can stop MySQL/MariaDB server on other WSL or (ii) you can stop the running WSL by opening a PowerShell and run `wsl -t DISTRO-NAME` - you can find the list of all `DISTRO-NAME` installed and their status (running/stopped) with `wsl -l -v`.

#1: Post edited by

zetyty‭ · 2023-07-20T14:48:34Z (10 months ago)
version 2: all info centrelized with tables for OS specificities

Copy Link

Raw

Markdown

> **Please don't edit this post (until with message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
~~1. [Prerequisites](#prerequisites)~~
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 1. Prerequisites
~~Some prerequisites (including Ruby and database server install) can differ depending on the OS or platform used (ex. Windows Subsystem Linux, WLS).~~
**Table 1** below gives some links to dedicated posts for specific platform.
|OS|Version tested|Link|
~~|-|-|-|~~
~~|Unix-based| |[**Unix-based answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/280452#answer-280452)|~~
|Fedora| | [**Fedora answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/287707#answer-287707)|
|Arch-based Linux| | [**Arch-based Linux and Windows answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/282191#answer-282191) |
|Windows| | [**Arch-based Linux and Windows answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/282191#answer-282191) |
|Debian-based| Debian 12 (and 11 on WSL2) | [**Debian-based (including on WSL) answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)|
| | Ubuntu 22.04.2 TLS (on WSL2) | [**Debian-based (including on WSL) answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)|
|WSL| WSL2 (Debian 11) | [**Debian-based (including on WSL) answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)|
| | WSL2 (Ubuntu 22.04.2 TLS) | [**Debian-based (including on WSL) answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)|
</div>
<div id="installing-qpixel">
# 2. Installing QPixel
First 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
Then, move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
## 3.1. Start 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).
**Table 2** below gives some links to posts where you could find how to start your database server.
~~|OS|Database|Link|~~
~~|-|-|-|~~
~~|Unix-based| MySQL |[**Unix-based answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/280452#answer-280452)|~~
|Fedora| "Community" MySQL | [**Fedora answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/287707#answer-287707)|
|Debian-based| MariaDB | [**Debian-based (including on WSL) answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)| (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)|
|WSL Debian-based| MariaDB | [**Debian-based (including on WSL) answer** of "How to set up a new (development) instance of Codidact/QPixel"](https://collab.codidact.org/posts/280451/288997#answer-288997)|
## 3.2. Create a new user and set up the database
~~Sign into the MySQL/MariaDB console with for e.g.:~~
```bash
sudo mysql -u root
```
~~And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword"):~~
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
Now 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:
```yml
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
```
**With MariaDB**, "you will need to replace all occurrences of `utf8mb4_0900_ai_ci` with `utf8mb4_unicode_ci` in `db/schema.rb`" (4 occurrences).
~~Create the rails database with:~~
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
Create a (first) community by opening the rails console with `rails c` and running these commands:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
Now run the following command to fill the database with necessary seed data.
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
~~You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):~~
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
~~Open a web browser and visit your server at 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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 5. New site setup
For the final step, 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>

> **Please don't edit or comment this post (until with message disappear) because it is still under discussion on [Collab Discord chat](https://discord.com/channels/634104110131445811/798943136809615370) (where you are welcome to participate)!!!**
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](https://github.com/codidact/qpixel/blob/develop/INSTALLATION.md).*
**This post is freely editable so, feel free to update/improve it!**
# Contents
1. [Prerequisites](#prerequisites)
1.1. [Initial prerequisites](#initial-prerequisites)
1.2. [Database server install](#database-server-install)
1.3. [Ruby install](#ruby-install)
2. [Installing QPixel](#installing-qpixel)
3. [Setting up the Database](#setting-up-the-database)
4. [Creating an administrator account](#creating-an-administrator-account)
5. [New site setup](#new-site-setup)
6. [Running the server in production](#running-the-server-in-production)
<div id="prerequisites">
# 1. Prerequisites
To run your own instance of QPixel you'll need at least:
* A Linux or Mac computer (Windows WSL2 is also okay, but slower; running Ruby on Windows is ultra-slow)
Also you'll need some prerequisites (including Ruby and database server install) which can differ depending on the OS or platform used (ex. Windows Subsystem Linux, WLS).
<div id="initial-prerequisites">
## 1.1. Initial prerequisites.
**Table 1** below gives some links to dedicated posts for specific platform.
<table>
<tr>
<td> OS </td> <td> Version tested </td> <td> Inline commands samples to install initial prerequisites</td>
</tr>
<tr>
<td> MacOS </td> <td> </td>
<td>
```bash
xcode-select --install
brew install bison
brew install redis
brew install imagemagick
# NodeJS install
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
```
</td>
</tr>
<tr>
<td> Debian-based </td>
<td>
- Debian 12 (and 11 on WSL2)
- Ubuntu 22.04.2 TLS (on WSL2)
</td>
<td>
```bash
sudo apt install gcc
sudo apt install make
sudo apt install default-libmysqlclient-dev # libmysqlclient-dev not disponible on Debian
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 curl
sudo apt install nodejs
sudo apt install redis
sudo apt install imagemagick
sudo apt install git
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
</td>
<td>
```bash
#dnf install gcc
#dnf install make
#dnf install libmagickwand-dev
#dnf install autoconf bison build-essential libssl-dev libyaml-dev libreadline-dev zlib1g-dev libncurses5-dev libffi-dev libgdbm-dev
#dnf install curl
#dnf install nodejs
#dnf install redis
#dnf install git
dnf install vips # is it really necessary?
dnf install ImageMagick-devel
dnf install mysql-devel
```
</td>
</tr>
</table>
</div>
<div id="database-server-install">
## 1.2. Database server install
<table>
<tr>
<td> OS </td> <td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td> MacOS </td>
<td>
```bash
brew install mysql openssl mysql-client
bundle config --global build.mysql2 --with-opt-dir="$(brew --prefix openssl)"
```
</td>
<td> </td>
</tr>
<tr>
<td> Debian-based </td>
<td>
MySQL is not available on the Debian default distribution, thus MariaDB can be installed instead[^2]
</td>
<td>
```bash
sudo apt install mariadb-server
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
```bash
dnf install community-mysql-server
```
</td>
<td>
</td>
</tr>
</table>
</div>
<div id="ruby-install">
## 1.3. Ruby install
QPixel is built with Ruby on Rails, therefore you'll need to install Ruby and we recommend [RVM](https://rvm.io/) or [rbenv](https://github.com/rbenv/rbenv#installation).
QPixel is tested with Ruby 3 (and works with Ruby 2.7 as of December 2022).
<details>
<summary>
Example with RVM on Debian:
</summary>
```bash
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):
```bash
source /home/zetyty/.rvm/scripts/rvm
```
Installation outputs sample on Debian 12 (for user "zetyty"):
```bash
~$ 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:
```bash
rvm install 3.1.2
```
</details>
</div>
</div>
<div id="installing-qpixel">
# 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*):
<details>
<summary>
```bash
git clone https://github.com/codidact/qpixel
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~$ 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.
```
</details>
After downloading QPixel, you need to install all the dependencies. For that, you need to move to the `qpixel` directory and run:
<details>
<summary>
```bash
bundle install
```
</summary>
Sample outputs on Debian (QPixel installed on `/home` directory):
```bash
~/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.
```
</details>
</div>
<div id="setting-up-the-database">
# 3. Setting up the Database
## 3.1. Start 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).
**Table 2** below gives some command line exemple to start your database server depending on the OS.
<table>
<tr>
<td> OS </td> <td> MySQL </td> <td> MariaDB </td>
</tr>
<tr>
<td> MacOS </td>
<td>
```bash
brew services start mysql
```
</td>
<td> </td>
</tr>
<tr>
<td> Debian-based </td>
<td>
</td>
<td>
```bash
sudo systemctl start mariadb
```
or
```bash
sudo service mariadb start
```
</td>
</tr>
<tr>
<td> Fedora </td>
<td>
```bash
systemctl enable mysqld
systemctl start mysqld
```
</td>
<td>
</td>
</tr>
</table>
**N.B. On WSL** we can't use `systemctl` but `service` instead (see [this answer](https://linux.codidact.com/posts/288812/288823#answer-288823)), 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].
## 3.2. Create a new user and set 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.:
```bash
sudo mysql -u root
```
And then type these lines (you can change the user name "qpixel@localhost" and password "myPassword" with secure ones):
<details>
<summary>
```sql
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
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
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
```
</details>
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):
```yml
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:
<details>
<summary>
```bash
rails db:create
rails db:schema:load
rails r db/scripts/create_tags_path_view.rb
rails db:migrate
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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:
<details>
<summary>
```ruby
Community.create(name: 'Dev Community', host: 'localhost:3000')
Rails.cache.clear
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
After that you can fill the database with necessary seed data, such as settings, help posts and default templates by running:
<details>
<summary>
```bash
rails db:seed
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
</div>
<div id="creating-an-administrator-account">
# 4. Creating an administrator account
Now comes the big moment: You can start the QPixel server for the first time with ([be sure to have `redis-server` already started](https://collab.codidact.org/posts/285407/285409#answer-285409)):
<details>
<summary>
```bash
rails s
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
<details>
<summary>
Sample outputs of the server stop on Debian:
</summary>
```ruby
^C- Gracefully stopping, waiting for requests to finish
=== puma shutdown: 2023-07-18 21:06:05 +0200 ===
- Goodbye!
Exiting
```
</details>
Open the rails console with `rails c` and run:
<details>
<summary>
```ruby
User.last.update(confirmed_at: DateTime.now, is_global_admin: true)
exit
```
</summary>
Sample outputs on Debian with MariaDB (QPixel installed on `/home/qpixel` directory):
```bash
:~/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
```
</details>
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.
</div>
<div id="new-site-setup">
# 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.
</div>
<div id="running-the-server-in-production">
# 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](https://collab.codidact.org/posts/287738).
</div>
[^1]: It seems taht the rails console can't run on WSL1 (but I got no problem with WSL2). Also, note that the install is significantly faster with WSL2.
[^2]: If you really want to install MySQL, you can take a look at [this discussion](https://linux.codidact.com/posts/288849), [this answer regarding Dockerized instance of MySQL on WSL or directly on the Windows Host](https://linux.codidact.com/posts/288812/288970#answer-288970) and [this official workflow](https://dev.mysql.com/doc/mysql-installation-excerpt/8.0/en/linux-installation-debian.html)).
[^3]: To stop MySQL on Windows: ppen a on command prompt and run `net stop MySQL80`. On other running WSL, (i) you can stop MySQL/MariaDB server on other WSL or (ii) you can stop the running WSL by opening a PowerShell and run `wsl -t DISTRO-NAME` - you can find the list of all `DISTRO-NAME` installed and their status (running/stopped) with `wsl -l -v`.

Communities

Post History