Skip to content

Latest commit

 

History

History
351 lines (248 loc) · 11.8 KB

README.md

File metadata and controls

351 lines (248 loc) · 11.8 KB
Raw

Project Template: React/Rails API

Description

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:

  1. In the Gemfile, replace gem 'pg', '~> 1.1' with gem 'sqlite3', '~> 1.4'.
  2. In the database.yml file, change the line adapter: postgresql to adapter: sqlite3.

Requirements

  • 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.

Setup

Start by cloning (not forking) the project template repository and removing the remote:

$ git clone [email protected]: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 [email protected]: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:

Make sure to also update this README to include documentation about your project. Here's a list of some awesome readmes for inspiration.

Deploying

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.

Create a Master Key File

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.

Create the App Database

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.

Create the Render Web Service

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:

Web service settings

Scroll down to the bottom of the page and click "Create Web Service". The deploy process will begin automatically.

Environment Setup

Install the Latest Ruby Version

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

Install NodeJS

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

Install Postgresql

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.

PostgreSQL Installation for WSL

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.

Postgresql Installation for OSX

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

Set Up a Render Account

You can sign up for a free account at https://dashboard.render.com/register. We recommend that you sign up 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 signup 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 sign up 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.

Troubleshooting

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 uninstall postgresql by running brew 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 run rails 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.

Resources