This project is scaffolded so that you can build a React frontend and Rails backend together, and easily deploy them to Render.
Note: if you are not planning to deploy your app to Render and prefer to use SQLite, you will need to make the following changes in the project files:
- In the
Gemfile
, replacegem 'pg', '~> 1.1'
withgem 'sqlite3', '~> 1.4'
. - In the
database.yml
file, change the lineadapter: postgresql
toadapter: sqlite3
.
- Ruby 2.7.4
- NodeJS (v16), and npm
- Render account
- Postgresql
See Environment Setup below for instructions on installing these tools if you don't already have them.
Start by cloning (not forking) the project template repository and removing the remote:
$ git clone git@github.com:learn-co-curriculum/project-template-react-rails-api.git your-project-name
$ cd your-project-name
$ git remote rm origin
Then, create a new remote repository on GitHub. Head to github.com and click the + icon in the top-right corner and follow the steps to create a new repository. Important: don't check any of the options such as 'Add a README file', 'Add a .gitignore file', etc. — since you're importing an existing repository, creating any of those files on GitHub will cause issues.
If you're working with a partner, add them as a collaborator on GitHub. From your repo on GitHub, go to Settings > Manage Access > Invite a collaborator and enter your partner's username. Once your partner has access, they should git clone (not fork) the repository.
Finally, connect the GitHub remote repository to your local repository and push up your code:
$ git remote add origin git@github.com:your-username/your-project-name.git
$ git push -u origin main
When you're ready to start building your project, run:
bundle install
rails db:create
npm install --prefix client
You can use the following commands to run the application:
rails s
: run the backend on http://localhost:3000npm start --prefix client
: run the frontend on http://localhost:4000
Make sure to also update this README to include documentation about your project. Here's a list of some awesome readmes for inspiration.
This application has all the starter code needed to help you deploy your application to Render. It's recommended to deploy your project early and push up changes often to ensure that your code works equally well in production and development environments.
The instructions in this section assume that you've already set up a Render account, created a PostgreSQL instance in your account, and set up your environment to deploy to Render. If you have not yet completed these steps, see the Environment Setup section below.
In the project files, delete the config/credentials.yml.enc
file. Then, in the
terminal, run the following:
$ EDITOR="code --wait" bin/rails credentials:edit
Note: if you use a different text editor than VS Code, you will need to replace
code
with the appropriate command.
The command above will open a file in VS Code and wait for you to close it
before completing the process of creating the credential files. Once you've done
that, you should see both the credentials.yml.enc
and master.key
files in
the config
folder. You will need the value in the master.key
file to set up
the web service in Render.
Commit your changes and push them to GitHub.
Render allows users to create multiple databases within a single PostgreSQL
instance using the PostgreSQL interactive terminal,
psql
.
Navigate to your PostgreSQL instance from the Render dashboard, click the "Connect" dropdown, then the External Connection tab, and copy the PSQL command. Paste it into your terminal and press enter. This command connects you to the remote PostgreSQL instance.
To create the database, run this SQL command:
CREATE DATABASE new_db_name;
Now if you run \l
from the PSQL prompt, you should see a table that includes
your main PostgreSQL instance as well as the database you just created.
Run the \q
command to exit PSQL.
To deploy, click the "New +" button in Render and select "Web Service". You'll see a list of all the repositories in your GitHub account. Find the repo you want to deploy and click the "Select" button.
In the page that opens, enter a name for your app and make sure the Environment is set to Ruby.
Scroll down and set the Build Command to ./bin/render-build.sh
and the Start
Command to bundle exec puma -C config/puma.rb
.
Open a separate tab in your browser, navigate to the Render dashboard, and click on your PostgreSQL instance. Scroll down to the "Connection" section, find the "Internal Database URL", and copy it.
Return to the other tab. Scroll down and click the "Advanced" button, then click
"Add Environment Variable." Enter DATABASE_URL
as the key, then paste in the
URL you just copied. Note that the URL will end with the name you gave your
PostgreSQL instance when you initially created it; be sure to remove that name
and replace it with the name of the database you created in the last section.
Click "Add Environment Variable" again. Add RAILS_MASTER_KEY
as the key, and
paste the value in the config/master.key
file you created earlier.
The completed page should look like this:
Scroll down to the bottom of the page and click "Create Web Service". The deploy process will begin automatically.
Verify which version of Ruby you're running by entering this in the terminal:
$ ruby -v
We recommend version 2.7.4. If you need to upgrade you can install it using rvm:
$ rvm install 2.7.4 --default
You should also install the latest versions of bundler
and rails
:
$ gem install bundler
$ gem install rails
Verify you are running a recent version of Node with:
node -v
If your Node version is not 16.x.x, install it and set it as the current and default version with:
nvm install 16
nvm use 16
nvm alias default 16
You can also update your npm version with:
npm i -g npm
Render requires that you use PostgreSQL for your database instead of SQLite. PostgreSQL (or just Postgres for short) is an advanced database management system with more features than SQLite. If you don't already have it installed, you'll need to set it up.
To install Postgres for WSL, run the following commands from your Ubuntu terminal:
sudo apt update
sudo apt install postgresql postgresql-contrib libpq-dev
Then confirm that Postgres was installed successfully:
psql --version
Run this command to start the Postgres service:
sudo service postgresql start
Finally, you'll also need to create a database user so that you are able to connect to the database from Rails. First, check what your operating system username is:
whoami
If your username is "ian", for example, you'd need to create a Postgres user with that same name. To do so, run this command to open the Postgres CLI:
sudo -u postgres -i
From the Postgres CLI, run this command (replacing "ian" with your username):
createuser -sr ian
Then enter control + d
or type logout
to exit.
This guide has more info on setting up Postgres on WSL if you get stuck.
To install Postgres for OSX, you can use Homebrew:
brew install postgresql
Once Postgres has been installed, run this command to start the Postgres service:
brew services start postgresql
You can # for a free account at https://dashboard.render.com/register. We recommend that you # using GitHub as that will make it a little easier for you to connect Render to your GitHub account. The instructions below assume you've done that.
Once you've completed the # process, you will be taken to the Render dashboard. In order to connect Render to your GitHub account, you'll need to click the "New Web Service" button in the "Web Services" box. On the next page, you will see a GitHub heading on the right side and below that a link labeled "Connect account". (If you didn't # using GitHub, it will say "Connect account" instead.) Click that link, then in the modal that appears click "Install." You should then be taken back to the "Create a New Web Service" page, which should now show a list of your GitHub repos. We won't actually create a web service just yet so you are free to navigate away from the page at this point.
Next, we'll set up a PostgreSQL instance. Click the "New +" button at the top of the page and select "PostgreSQL". Enter a name for your PostgreSQL instance. The remaining fields can be left as is. Click "Create Database" at the bottom of the page. You should now be all set to follow the steps in the "Deploying" section.
If you ran into any errors along the way, here are some things you can try to troubleshoot:
-
If you're on a Mac and got a server connection error when you tried to run
rails db:create
, one option for solving this problem for Mac users is to install the Postgres app. To do this, first uninstallpostgresql
by runningbrew remove postgresql
. Next, download the app from the Postgres downloads page and install it. Launch the app and click "Initialize" to create a new server. You should now be able to runrails db:create
. -
If you're using WSL and got the following error running
rails db:create
:PG::ConnectionBad: FATAL: role "yourusername" does not exist
The issue is that you did not create a role in Postgres for the default user account. Check this video for one possible fix.
-
If your app failed to deploy at the build stage, make sure your local environment is set up correctly by following the steps at the beginning of this lesson. Check that you have the latest versions of Ruby and Bundler, and ensure that PostgreSQL was installed successfully.
-
If you deployed successfully, but you ran into issues when you visited the site, make sure you migrated and seeded the database. Also, make sure that your application works locally and try to debug any issues on your local machine before re-deploying. You can also check the deployment log on the app's page in the Render dashboard.