2018-07-24 02:29:31 +00:00
**DO NOT READ THIS FILE ON GITHUB, GUIDES ARE PUBLISHED ON https://guides.rubyonrails.org.**
2014-12-23 22:32:50 +00:00
2023-02-06 06:45:16 +00:00
Installing Rails Core Development Dependencies
==============================================
2012-10-17 13:15:55 +00:00
2019-08-09 21:30:15 +00:00
This guide covers how to set up an environment for Ruby on Rails core development.
2012-10-17 13:15:55 +00:00
2012-11-29 22:25:02 +00:00
After reading this guide, you will know:
2013-05-02 02:14:33 +00:00
* How to set up your machine for Rails development
2012-10-17 13:15:55 +00:00
--------------------------------------------------------------------------------
2022-03-24 21:22:18 +00:00
Other Ways to Set Up Your Environment
-------------------------------------
2012-10-17 13:15:55 +00:00
2022-05-03 18:46:38 +00:00
If you don't want to set up Rails for development on your local machine, you can use Codespaces, the VS Code Remote Plugin, or rails-dev-box. Learn more about these options [here ](contributing_to_ruby_on_rails.html#setting-up-a-development-environment ).
2012-10-17 13:15:55 +00:00
2022-03-24 21:22:18 +00:00
Local Development
-----------------
2012-10-17 13:15:55 +00:00
2022-05-19 01:41:45 +00:00
If you want to develop Ruby on Rails locally on your machine, see the steps below.
2012-10-17 13:15:55 +00:00
### Install Git
2022-03-24 21:22:18 +00:00
Ruby on Rails uses Git for source code control. The [Git homepage ](https://git-scm.com/ ) has installation instructions. There are a variety of resources online that will help you get familiar with Git.
2012-10-17 13:15:55 +00:00
### Clone the Ruby on Rails Repository
2022-03-24 21:22:18 +00:00
Navigate to the folder where you want to download the Ruby on Rails source code (it will create its own `rails` subdirectory) and run:
2012-10-17 13:15:55 +00:00
```bash
2017-08-18 16:55:46 +00:00
$ git clone https://github.com/rails/rails.git
2012-10-17 13:15:55 +00:00
$ cd rails
```
2018-05-13 19:37:44 +00:00
### Install Additional Tools and Services
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
Some Rails tests depend on additional tools that you need to install before running those specific tests.
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
Here's the list of each gems' additional dependencies:
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
* Action Cable depends on Redis
* Active Record depends on SQLite3, MySQL and PostgreSQL
* Active Storage depends on Yarn (additionally Yarn depends on
2022-06-02 01:20:53 +00:00
[Node.js ](https://nodejs.org/ )), ImageMagick, libvips, FFmpeg, muPDF,
Poppler, and on macOS also XQuartz.
2018-05-13 19:37:44 +00:00
* Active Support depends on memcached and Redis
* Railties depend on a JavaScript runtime environment, such as having
[Node.js ](https://nodejs.org/ ) installed.
2013-07-29 13:46:09 +00:00
2018-05-13 19:37:44 +00:00
Install all the services you need to properly test the full gem you'll be
2022-03-24 21:22:18 +00:00
making changes to. How to install these services for macOS, Ubuntu, Fedora/CentOS,
2022-05-01 07:07:21 +00:00
Arch Linux, and FreeBSD are detailed below.
2013-07-29 13:46:09 +00:00
2022-03-24 21:22:18 +00:00
NOTE: Redis' documentation discourages installations with package managers as those are usually outdated. Installing from source and bringing the server up is straight forward and well documented on [Redis' documentation ](https://redis.io/download#installation ).
2012-10-17 13:15:55 +00:00
2022-03-24 21:22:18 +00:00
NOTE: Active Record tests _must_ pass for at least MySQL, PostgreSQL, and SQLite3. Your patch will be rejected if tested against a single adapter, unless the change and tests are adapter specific.
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
Below you can find instructions on how to install all of the additional
2022-03-24 21:22:18 +00:00
tools for different operating systems.
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
#### macOS
2013-08-16 11:04:28 +00:00
2018-05-13 19:37:44 +00:00
On macOS you can use [Homebrew ](https://brew.sh/ ) to install all of the
additional tools.
2013-08-16 11:04:28 +00:00
2018-05-13 19:37:44 +00:00
To install all run:
2013-08-16 11:04:28 +00:00
```bash
2018-05-13 19:37:44 +00:00
$ brew bundle
2013-08-16 11:04:28 +00:00
```
2018-05-13 19:37:44 +00:00
You'll also need to start each of the installed services. To list all
available services run:
2013-08-16 11:04:28 +00:00
```bash
2018-05-13 19:37:44 +00:00
$ brew services list
2013-08-16 11:04:28 +00:00
```
2018-05-13 19:37:44 +00:00
You can then start each of the services one by one like this:
2013-08-16 11:04:28 +00:00
```bash
2018-05-13 19:37:44 +00:00
$ brew services start mysql
2013-08-16 11:04:28 +00:00
```
2018-05-13 19:37:44 +00:00
Replace `mysql` with the name of the service you want to start.
2014-08-24 17:29:11 +00:00
2018-05-13 19:37:44 +00:00
#### Ubuntu
2014-08-24 17:29:11 +00:00
2018-05-13 19:37:44 +00:00
To install all run:
2012-10-17 13:15:55 +00:00
```bash
2018-05-13 19:37:44 +00:00
$ sudo apt-get update
2022-06-02 01:20:53 +00:00
$ sudo apt-get install sqlite3 libsqlite3-dev mysql-server libmysqlclient-dev postgresql postgresql-client postgresql-contrib libpq-dev redis-server memcached imagemagick ffmpeg mupdf mupdf-tools libxml2-dev libvips42 poppler-utils
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
# Install Yarn
2023-03-27 01:19:09 +00:00
# Use this command if you do not have Node.js installed
2023-11-03 09:56:02 +00:00
# ref: https://github.com/nodesource/distributions#installation-instructions
$ sudo mkdir -p /etc/apt/keyrings
$ curl --fail --silent --show-error --location https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg
$ echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_20.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list
$ sudo apt-get update
2023-03-27 01:19:09 +00:00
$ sudo apt-get install -y nodejs
2023-11-03 09:56:02 +00:00
2023-03-27 01:19:09 +00:00
# Once you have installed Node.js, install the yarn npm package
$ sudo npm install --global yarn
2012-10-17 13:15:55 +00:00
```
2018-05-13 19:37:44 +00:00
#### Fedora or CentOS
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
To install all run:
2012-10-17 13:15:55 +00:00
```bash
2023-12-29 21:14:15 +00:00
$ sudo dnf install sqlite-devel sqlite-libs mysql-server mysql-devel postgresql-server postgresql-devel redis memcached ImageMagick ffmpeg mupdf libxml2-devel vips poppler-utils
2013-08-21 23:00:47 +00:00
2018-05-13 19:37:44 +00:00
# Install Yarn
# Use this command if you do not have Node.js installed
2023-11-03 09:56:02 +00:00
# ref: https://github.com/nodesource/distributions#installation-instructions-1
$ sudo dnf install https://rpm.nodesource.com/pub_20/nodistro/repo/nodesource-release-nodistro-1.noarch.rpm -y
$ sudo dnf install nodejs -y --setopt=nodesource-nodejs.module_hotfixes=1
2023-03-27 01:19:09 +00:00
# Once you have installed Node.js, install the yarn npm package
$ sudo npm install --global yarn
2013-08-21 23:00:47 +00:00
```
2018-05-13 19:37:44 +00:00
#### Arch Linux
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
To install all run:
2012-10-17 13:15:55 +00:00
```bash
2022-06-02 01:20:53 +00:00
$ sudo pacman -S sqlite mariadb libmariadbclient mariadb-clients postgresql postgresql-libs redis memcached imagemagick ffmpeg mupdf mupdf-tools poppler yarn libxml2 libvips poppler
2020-01-04 01:15:43 +00:00
$ sudo mariadb-install-db --user=mysql --basedir=/usr --datadir=/var/lib/mysql
$ sudo systemctl start redis mariadb memcached
2012-10-17 13:15:55 +00:00
```
2018-05-13 19:37:44 +00:00
NOTE: If you are running Arch Linux, MySQL isn't supported anymore so you will need to
use MariaDB instead (see [this announcement ](https://www.archlinux.org/news/mariadb-replaces-mysql-in-repositories/ )).
2013-07-24 16:12:00 +00:00
2018-05-13 19:37:44 +00:00
#### FreeBSD
2013-07-24 16:12:00 +00:00
2018-05-13 19:37:44 +00:00
To install all run:
2013-07-29 13:46:09 +00:00
```bash
2022-06-02 22:59:05 +00:00
$ sudo pkg install sqlite3 mysql80-client mysql80-server postgresql11-client postgresql11-server memcached imagemagick6 ffmpeg mupdf yarn libxml2 vips poppler-utils
2018-05-13 19:37:44 +00:00
# portmaster databases/redis
2014-04-06 18:57:20 +00:00
```
2018-11-20 15:36:47 +00:00
Or install everything through ports (these packages are located under the
2018-05-13 19:37:44 +00:00
`databases` folder).
2013-07-29 13:46:09 +00:00
2022-03-24 21:22:18 +00:00
NOTE: If you run into problems during the installation of MySQL, please see
2019-10-04 00:22:29 +00:00
[the MySQL documentation ](https://dev.mysql.com/doc/refman/en/freebsd-installation.html ).
2012-10-17 13:15:55 +00:00
2023-03-27 02:17:32 +00:00
#### Debian
To install all dependencies run:
```bash
$ sudo apt-get install sqlite3 libsqlite3-dev default-mysql-server default-libmysqlclient-dev postgresql postgresql-client postgresql-contrib libpq-dev redis-server memcached imagemagick ffmpeg mupdf mupdf-tools libxml2-dev libvips42 poppler-utils
```
NOTE: If you are running Debian, MariaDB is the default MySQL server, so be aware there may be differences.
2018-05-13 19:37:44 +00:00
### Database Configuration
2012-10-17 13:15:55 +00:00
2018-05-13 19:37:44 +00:00
There are couple of additional steps required to configure database engines
required for running Active Record tests.
2012-10-17 13:15:55 +00:00
2019-08-09 21:30:15 +00:00
PostgreSQL's authentication works differently. To set up the development environment
2014-08-24 17:29:11 +00:00
with your development account, on Linux or BSD, you just have to run:
2012-10-17 13:15:55 +00:00
```bash
$ sudo -u postgres createuser --superuser $USER
```
2014-08-24 17:29:11 +00:00
2017-08-18 15:39:25 +00:00
and for macOS:
2014-08-24 17:29:11 +00:00
2014-04-06 18:57:20 +00:00
```bash
$ createuser --superuser $USER
```
2012-10-17 13:15:55 +00:00
2023-02-14 08:39:29 +00:00
NOTE: MySQL will create the users when the databases are created. The task assumes your user is `root` with no password.
2022-03-24 21:22:18 +00:00
2018-05-13 19:37:44 +00:00
Then, you need to create the test databases for both MySQL and PostgreSQL with:
2012-10-17 13:15:55 +00:00
```bash
$ cd activerecord
2018-05-13 19:37:44 +00:00
$ bundle exec rake db:create
2012-10-17 13:15:55 +00:00
```
2018-05-13 19:37:44 +00:00
You can also create test databases for each database engine separately:
2013-01-23 15:15:31 +00:00
```bash
$ cd activerecord
2018-05-13 19:37:44 +00:00
$ bundle exec rake db:mysql:build
$ bundle exec rake db:postgresql:build
2013-01-23 15:15:31 +00:00
```
2018-05-13 19:37:44 +00:00
and you can drop the databases using:
2013-01-23 15:15:31 +00:00
```bash
$ cd activerecord
$ bundle exec rake db:drop
```
2017-08-18 15:39:25 +00:00
NOTE: Using the Rake task to create the test databases ensures they have the correct character set and collation.
2012-10-17 13:15:55 +00:00
2022-03-24 21:22:18 +00:00
If you're using another database, check the file `activerecord/test/config.yml` or `activerecord/test/config.example.yml` for default connection information. You can edit `activerecord/test/config.yml` to provide different credentials on your machine, but you should not push any of those changes back to Rails.
2016-08-22 17:35:33 +00:00
2022-10-14 23:27:28 +00:00
### Install JavaScript Dependencies
2016-08-22 17:35:33 +00:00
2021-04-15 11:52:58 +00:00
If you installed Yarn, you will need to install the JavaScript dependencies:
2017-08-18 15:31:19 +00:00
```bash
2018-08-16 10:31:24 +00:00
$ yarn install
2017-08-18 15:31:19 +00:00
```
2018-05-27 10:06:11 +00:00
2022-10-14 23:27:28 +00:00
### Installing Gem Dependencies
2018-05-27 10:06:11 +00:00
2022-03-24 21:22:18 +00:00
Gems are installed with [Bundler ](https://bundler.io/ ) which ships by default with Ruby.
2018-05-27 10:06:11 +00:00
2022-03-24 21:22:18 +00:00
To install the Gemfile for Rails run:
2018-05-27 10:06:11 +00:00
```bash
2018-05-13 19:37:44 +00:00
$ bundle install
2018-05-27 10:06:11 +00:00
```
2022-05-19 01:41:45 +00:00
If you don't need to run Active Record tests, you can run:
2018-05-27 10:06:11 +00:00
```bash
2018-05-13 19:37:44 +00:00
$ bundle install --without db
2018-08-09 18:08:31 +00:00
```
2018-05-13 19:37:44 +00:00
### Contribute to Rails
2018-08-22 02:35:09 +00:00
2019-08-09 21:30:15 +00:00
After you've set up everything, read how you can start [contributing ](contributing_to_ruby_on_rails.html#running-an-application-against-your-local-branch ).