Note: MacOS ships with a version of Ruby, needed for various operating systems. To avoid causing an issue with your operating system you should use a version manager for Ruby.
If you don't already have a Ruby version manager, we highly recommend rbenv. This will allow you to have different versions running on a per project basis. The MacOS system version of Ruby will stay intact while giving you the ability to use the version needed for this Forem project. Please follow their installation guide.
With the Ruby version manager, install the Ruby version listed on our badge. (i.e. with rbenv: rbenv install $(cat .ruby-version)
)
Note: The repository must be forked and cloned before running the rbenv install $(cat .ruby-version)
command.
Please refer to their installation guide.
Forem requires PostgreSQL version 11 or higher to run.
The easiest way to get started is to use Postgres.app. Alternatively, check out the official PostgreSQL site for more installation options.
For additional configuration options, check our PostgreSQL setup guide.
Forem uses ImageMagick to manipulate images on upload.
You can install ImageMagick with brew install imagemagick
.
Forem requires Redis version 6.0 or higher to run.
We recommend using Homebrew:
1
brew install redis
you can follow the post installation instructions, we recommend using brew services
to start Redis in the background:
1
brew services start redis
You can test if it's up and running by issuing the following command:
1
redis-cli ping
Forem requires Elasticsearch 7.x to run. We recommend version 7.5.2.
You have the option of installing Elasticsearch with Homebrew or through an archive. We recommend installing from archive on Mac.
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 themselves, so check those out if you run into any issues or want further information. Make sure to download the OSS version of Elasticsearch, elasticsearch-oss
.
Please note that you will need wget
in order to proceed with this installation (brew install wget
).
1 2 3 4
wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-7.5.2-darwin-x86_64.tar.gz wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-oss-7.5.2-darwin-x86_64.tar.gz.sha512 shasum -a 512 -c elasticsearch-oss-7.5.2-darwin-x86_64.tar.gz.sha512 tar -xzf elasticsearch-oss-7.5.2-darwin-x86_64.tar.gz
To start elasticsearch, make sure you are in the correct directory:
1
cd elasticsearch-7.5.2
You can then start it by running:
1
./bin/elasticsearch
To start elasticsearch as a daemonized process:
1
./bin/elasticsearch -d
To install Elasticsearch with Homebrew we will use the following commands to:
1 2 3
brew tap elastic/tap brew install elastic/tap/elasticsearch-oss brew pin elasticsearch-oss
After installation you can manually test if the Elasticsearch server starts by issuing the command elasticsearch
in the shell. You can then start the server as a service with brew services start elasticsearch-oss
.
You can find further info on your local Elasticsearch installation by typing brew info elastic/tap/elasticsearch-oss
.
Two possible startup issues you might encounter:
java.nio.file.FileSystemLoopException
:1 2
Exception in thread "main" org.elasticsearch.bootstrap.BootstrapException: java.nio.file.FileSystemLoopException: /usr/local/etc/elasticsearch/elasticsearch Likely root cause: java.nio.file.FileSystemLoopException: /usr/local/etc/elasticsearch/elasticsearch
This happens because the installation of Elasticsearch might have a recursive link in the configuration directory causing the infinite loop:
1 2
> ll /usr/local/etc/elasticsearch elasticsearch -> /usr/local/etc/elasticsearch
By manually removing the link with rm -i /usr/local/etc/elasticsearch/elasticsearch
the issue should be fixed.
java.lang.IllegalStateException
:1 2
java.lang.IllegalStateException: Could not load plugin descriptor for plugin directory [plugins] Likely root cause: java.nio.file.NoSuchFileException: /usr/local/Cellar/elasticsearch-oss/7.6.0/libexec/plugins/plugins/plugin-descriptor.properties
This happens for a similar reason as the previous error, the installation might create a recursive link in the plugins directory.
1 2
> ll /usr/local/var/elasticsearch/plugins plugins -> /usr/local/var/elasticsearch/plugins
By manually removing the link with rm -i /usr/local/var/elasticsearch/plugins/plugins
the issue should be fixed.
Once installed and started you can test if it's up and running correctly by issuing the following command:
1
curl http://localhost:9200
You should receive in response a JSON document containing some information about your local Elasticsearch installation, for example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
{ "name": "hostname", "cluster_name": "elasticsearch_...", "cluster_uuid": "...", "version": { "number": "7.5.2", "build_flavor": "oss", "build_type": "tar", "build_hash": "8bec50e1e0ad29dad5653712cf3bb580cd1afcdf", "build_date": "2020-01-15T12:11:52.313576Z", "build_snapshot": false, "lucene_version": "8.3.0", "minimum_wire_compatibility_version": "6.8.0", "minimum_index_compatibility_version": "6.0.0-beta1" }, "tagline": "You Know, for Search" }
Clone your forked repository in one of two ways:
git clone https://github.com/<your-username>/forem.git
git clone git@github.com:<your-username>/forem.git
gem install bundler
Set up your environment variables/secrets
.env_sample
to see all the ENV
variables we use and the fake default provided for any missing keys.APP_DOMAIN
variable to the remote computer's domain name.For any key that you wish to enter/replace, follow the steps below.
.env
by copying from the provided template (i.e. with bash: cp .env_sample .env
). This is a personal file that is ignored in git.1 2 3
export CLOUDINARY_API_KEY="SOME_REAL_SECURE_KEY_HERE" export CLOUDINARY_API_SECRET="ANOTHER_REAL_SECURE_KEY_HERE" export CLOUDINARY_CLOUD_NAME="A_CLOUDINARY_NAME"
You do not need "real" keys for basic development. Some features require certain keys, so you may be able to add them as you go.
Run bin/setup
Error: rbenv install hangs at ruby-build: using readline from homebrew
Solution: Stackoverflow answer RUBY_CONFIGURE_OPTS=--with-readline-dir="$(brew --prefix readline)" rbenv install 2.0.0
Error: __NSPlaceholderDate initialize] may have been in progress in another thread when fork() was called
Solution: Run the command export OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES
(or set -x OBJC_DISABLE_INITIALIZE_FORK_SAFETY YES
in fish shell)
Error: User does not have CONNECT privilege.
Solution: Complete the steps outlined in the PostgreSQL setup guide.
Error: rbenv: version '<version number>' is not installed (set by /Path/To/Local/Repository/.ruby-version)
Solution: Run the command rbenv install <version number>
Error: ruby-build: definition not found: <version number>
when rbenv
was installed via brew
.
1 2 3 4
ruby-build: definition not found: <version number> See all available versions with `rbenv install --list`. If the version you need is missing, try upgrading ruby-build:
Solution: Run the following to update ruby-build
, brew update && brew upgrade ruby-build
. After that, rerun rbenv install <version number>
and that version will get installed.
Error:
1 2 3 4 5 6
== Preparing database == Sorry, you can't use byebug without Readline. To solve this, you need to rebuild Ruby with Readline support. If using Ubuntu, try `sudo apt-get install libreadline-dev` and then reinstall your Ruby. rails aborted! LoadError: dlopen(/Users/<username>/.rbenv/versions/2.6.5/lib/ruby/2.6.0/x86_64-darwin18/readline.bundle, 9): Library not loaded: /usr/local/opt/readline/lib/libreadline.<some version number>.dylib
Solution: Run ln -s /usr/local/opt/readline/lib/libreadline.dylib /usr/local/opt/readline/lib/libreadline.<some version number>.dylib
from the command line then run bin/setup
again. You may have a different version of libreadline, so replace <some version number>
with the version that errored.
Error:
1 2
PG::Error: ERROR: invalid value for parameter "TimeZone": "UTC" : SET time zone 'UTC'
Solution: Restart your Postgres.app, or, if you installed PostgreSQL with Homebrew, restart with:
1
brew services restart postgresql
If that doesn't work, reboot your Mac.
Error:
1 2 3 4 5
ERROR: Error installing pg: ERROR: Failed to build gem native extension. [...] Can't find the 'libpq-fe.h header *** extconf.rb failed ***
Solution: You may encounter this when installing PostgreSQL with the Postgres.app. Try restarting the app and reinitializing the database. If that doesn't work, install PostgreSQL with Homebrew instead: brew install postgresql
If you encountered any errors that you subsequently resolved, please consider updating this section with your errors and their solutions.