These prerequisites assume you're working on a
64-bit Windows 10 operating system machine updated to version 2004, Build 19041 or higher. To check your Windows version, press
Win Logo key +
winver, then click OK.
There are other ways to get Forem running on lower versions, but we recommend a complete WSL 2 installation.
Since Forem's codebase is using the Ruby on Rails framework, we will need to install the Windows Subsystem for Linux (WSL). Some dependencies used by the source code triggered errors when installing on Windows, so using WSL allows you to work on the software and not having to fix gem incompatibilities.
Follow the instructions for Installing the Windows Subsystem for Linux. Once you've installed WSL, complete all the instructions under the following sections in the link above:
Once all the steps mentioned above are completed, install Ubuntu 18.04 on Windows.
On your first run, the system will ask for username and password. Take note of both since it will be used for
sudo commands. More information about the process can be found at create a user account and password for your new Linux distribution
rbenv is a version manager for Ruby applications which allows one to guarantee that the Ruby version in development environment matches production. First, install Ruby language dependencies before installing
sudo apt-get update sudo apt-get install git-core curl zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
Now, we install rbenv using the following commands:
1 2 3 4 5 6 7 8 9
cd git clone https://github.com/rbenv/rbenv.git ~/.rbenv echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc echo 'eval "$(rbenv init -)"' >> ~/.bashrc exec $SHELL git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build echo 'export PATH="$HOME/.rbenv/plugins/ruby-build/bin:$PATH"' >> ~/.bashrc exec $SHELL
One can verify
rbenv installation using the
rbenv-doctor script with the following commands:
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/master/bin/rbenv-doctor | bash
As a pre-requisite to install Rails, Node.js needs to be installed. nvm is a Node.js version manager that helps a developer select a specific Node.js version for development.
nvm, follow the instructions outlined in the official nvm documentation.
Be sure to reload the shell with the command
exec $SHELL after the installation is complete.
Run the following command to verify that
nvm is installed:
command -v nvm
If the shell outputs
nvm, the installation is successful. Installation of the correct Node.js version will be done in a later part of the installation process.
The fastest way to install Yarn for WSL would be from Debian package repository. Configure the repository with the following commands:
curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
Since we do not have Node.js installed yet, we will be installing Yarn without the default Node.js with the following command:
sudo apt update && sudo apt install --no-install-recommends yarn
To verify Yarn's installation, run the command
yarn -v. It should print
Yarn requires Node.js 4.0 or higher to be installed.. This indicates that the Yarn installation succeeded but Node.js still needs to be installed for it to work fully. We install Node.js later on in the installation process.
Forem requires PostgreSQL version 11 or higher. To Install PostgreSQL on WSL, follow steps under the PostgreSQL APT Repository section.
Once Installed, perform the following steps in order to set up a username and password for PostgreSQL:
sudo -i service postgresql startto start the server.
$YOUR_USERNAME in the following commands with your Linux Username and execute them:
1 2 3
sudo -u postgres createuser -s $YOUR_USERNAME createdb sudo -u $YOUR_USERNAME psql
\passwordto set a password for your PostgreSQL user.
For additional configuration options, check our PostgreSQL setup guide.
Forem uses ImageMagick to manipulate images on upload.
ImageMagick can be installed to WSL via installing its imagemagick package with the following command:
sudo apt update && sudo apt install imagemagick
To verify its installation, run
identify -version command.
Forem requires Redis version 4.0 or higher.
We recommend to follow this guide to run Redis under WSL.
Forem requires a version of Elasticsearch between 7.1 and 7.5. Version 7.6 is not supported. We recommend version 7.5.2.
We recommend that you do not install Elasticsearch in the app directory. Instead, we recommend installing it in your home directory (for example,
cd $HOME). (This also ensures that we don't accidentally commit Elasticsearch code to the project's repository!)
The following directions were taken from the Elasticsearch docs, check them out to learn more about the installation process and troubleshooting issues. Make sure to refer to the OSS version,
elasticsearch-oss while going through the Elasticsearch docs.
To install Elasticsearch perform the following steps:
Execute the following commands:
1 2 3 4 5
cd wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-7.5.2-linux-x86_64.tar.gz wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-7.5.2-linux-x86_64.tar.gz.sha512 shasum -a 512 -c elasticsearch-oss-7.5.2-linux-x86_64.tar.gz.sha512 tar -xzf elasticsearch-oss-7.5.2-linux-x86_64.tar.gz
Next, switch to the correct directory with:
To start Elasticsearch, run the following command:
or, start it as a daemonized process with:
Once Elasticsearch is running, verify Elasticsearch's installation by executing the
cURL command as follows:
curl -X GET "localhost:9200/?pretty"
git clone https://github.com/<your-username>/forem.git
Open the cloned forem folder in terminal with
cd forem. Next, install Ruby with the following commands:
1 2 3
rbenv install $(cat .ruby-version) rbenv global $(cat .ruby-version) ruby -v
Install Node.js with the following set of commands:
1 2 3 4
nvm install $(cat .nvmrc) nvm use $(cat .nvmrc) node -v yarn -v
gem install bundler
Set up your environment variables/secrets
Envfile. This file lists all the
ENVvariables we use and provides a fake default for any missing keys.
APP_DOMAINvariable to the remote computer's domain name.
For any key that you wish to enter/replace:
.envby copying from the provided template (ie. with bash:
cp .env_sample .env). This is a personal file that is ignored in git.
export GITHUB_KEY="SOME_REAL_SECURE_KEY_HERE" export GITHUB_SECRET="ANOTHER_REAL_SECURE_KEY_HERE"
ENVvariables on bootup, the envied gem will alert you with messages similar to
'error_on_missing_variables!': The following environment variables should be set: A_MISSING_KEY..
After ensuring that Elasticsearch, the PostgreSQL server, and the Redis server are running, run
bin/setupscript is responsible for installing a varienty of dependencies. One can find it inside the
binfolder by the name of
- Its first task is to install the
bundlergem. Next, it will make
bundlerinstall all the gems, including
Rails, located in
Gemfilein the root of the repository. It also installs
bin/yarnfile. These dependencies are located in
package.jsonin the root of the repository.
- Next, it uses various Rake files located inside the
libfolder to setup ElasticSearch environment, PostgreSQL database creation and updation.
- Finally it cleans up all the log files and restarts the Puma server.
There is a possibility that you might encounter a statement timeout when seeding the database for the first time. Please increase the value of
If the installation process failed with the following error
ERROR: Error installing pg. Please consider installing the following package
sudo apt-get install libpq-dev
bin/setupfails at installing
cld-0.8.0with the warnings
'aclocal-1.10' is missing on your systemand
'automake-1.10' is missing on your system. Please install
automake-1.10using the commands below.
1 2 3 4 5 6 7 8
cd sudo apt-get update sudo apt-get install autoconf wget https://ftp.gnu.org/gnu/automake/automake-1.10.tar.gz tar xf automake-1.10.tar.gz cd automake-1.10/ ./configure --prefix=/usr/local make
In WSL2, hostname/IP address are no longer shared between Windows and Linux. There are currently two work-arounds.
Use dockerized selenium, ie docker-selenium. You will need docker for the following steps
docker run -d --name selenium-hub -p 4444:4444 selenium/hub:3.141.59-20200409
CH=$(docker run --rm --name=ch --link selenium-hub:hub -v /dev/shm:/dev/shm selenium/node-chrome:3.141.59-20200409)
export SELENIUM_URL="http://localhost:4444/wd/hub"to your
Port forward with
socats (more info needed).
If you encountered any errors that you subsequently resolved, please consider updating this section with your errors and their solutions.