June 10th, 2020

Setup Spina CMS with Ruby on Rails 6 and Digital Ocean

Spina is an excellent CMS platform for creating a Ruby on Rails website with editable content. I’ve used it for two large website projects, and although it has it’s quirks, it’s a great platform to integrate into your project to make your website easily editable without the need to touch code.

In this tutorial, I’ll walk you through how to setup a Ruby on Rails project with Spina. It’s similar to my previous tutorial, but differs in some important ways.

Covered in this guide:

• Setup a local development environment
• Install and setup Ruby on Rails with PostgreSQL
• Install and configure Spina
• Configure and deploy to Digital Ocean server via Capistrano

What we’ll be using:

• Spina v1.1.4
  • This version is important as it fixes a key SASS issue with any version of Rails after 6.0.2.1.
• Rails 6.0.2.1
  • Newer versions of Rails should work as well.
• PostgreSQL
• Capistrano
  • Used for deployments.
• Digital Ocean

Let’s get started!

1. Setting up Ruby on Rails with PostgreSQL

Up until using Spina, I had only used Postgres in a hobbyist capacity. However, if you’re familiar with any other SQL database (MySQL for example), Postgres is similar and easy to use.

Create a new Rails project by running the following (feel free to change ‘new-spina-app’ to whatever name you’d like):

rails new new-spina-app --database=postgresql

And you’re done! You can move onto Step 2.

1.5. Older versions of Spina (v1.1.3 or older)

Spina v1.1.3 is broken for any Rails version above 6.0.2.1. Spina v1.1.4 appears to have fixed the issue, so most likely you can skip these steps. But just in case, here is how you can manually install an older version of Rails if you’d like to use an older version of Spina.

# Only needed if you want to install an older version of Spina before 1.1.4

mkdir new-spina-app # Make a new folder
cd new-spina-app # Navigate into that folder

echo "source 'https://rubygems.org'" > Gemfile # Create your Gemfile
echo "gem 'rails', '6.0.2.1'" >> Gemfile # Specify your version of Rails
bundle install # Install from the Gemfile you created

bundle exec rails -v # Check you're using the right Rails version (should be 6.0.2.1)
bundle exec  rails new . --force --skip-bundle --database=postgresql # Create a new Rails project w/ PostgreSQL

Next, open up your Gemfile and edit the gem 'rails', '~> 6.0.0', '>= 6.0.2.1' line (somewhere towards the top) to the following:

gem 'rails', '6.0.2.1'

Then finish it off by running the final command in your Terminal:

bundle update

Phew, all done.

2. Databases

Next, let’s create and build the local app databases (these are defined within your /config/database.yml file). Navigate your terminal into your newly created Rails app folder and run:

rake db:create
rake db:migrate

Next let’s start your server to make sure the basics are working. Start it via:

rails s

Navigate your favorite browser to localhost:3000 and you should see the Rails welcome page.

3. Install and configure Spina

Next, let’s add Spina. Open up your Gemfile and add the following:

gem 'spina'

Save, then run the following commands:

bundle install
rails g spina:install

Follow the steps to setup your new website (for theme, I always choose default). When done, start your server again (rails s) and navigate to localhost:3000/admin in your browser. You should see the login page.

If you can see the Homepage in both the Spina admin dashboard and on localhost:3000, you’re all set!

A quick overview of Spina

I’m not going to go into all the parts of Spina, but enough to get your footing.

HTML

Spina uses templates. Each new page you create looks for a specified template you create. This is important to understand for how pages are made.

All the HTML/HAML/ERB pages (Spina defaults to HAML but I just rename them to ERB and update the contents) are located at /views/default/pages. If you open up the homepage file, you can make updates and they’ll be reflected when refreshing the browser.

Layouts are located in /views/layouts/default.

CSS

CSS is all located at /assets/stylesheets/default/application.css.sass. I don’t like SASS, so I always rename this file to application.scss and restructure my CSS/SCSS accordingly.

Javascript

By default, Rails 6 uses Webpacker, and therefore so does Spina. Files are located in /javascript.

Creating a new page

The Spina documentation does a good job breaking down how to add a new page.

4. Deploying Spina to Digital Ocean via Capistrano

4.1. Setting up the server

Navigate to Digital Ocean and create a new droplet with a Ruby on Rails image.

As of this writing, it’s using Rails 6.0.2.1, but you should confirm that as you may have to install the correct version if they’ve changed it. Alternatively, you can install Ruby/Rails/Postgres from scratch yourself, but this way saves a lot of time.

4.2. Configure Server

First things first, let’s SSH into our new Digital Ocean server. Once in, DO adds a file that has all the login info we’ll need for our Postgres database. They automatically make a rails user for us, so we’ll just need to get the password. To get it, run this command and copy the RAIL_POSTGRESS_PASS password somewhere for use in a little bit:

cat ~/.digitalocean.passwords

Now, we need to setup our Postgres server. If you’ve done the One-Click setup, Postgres is already up and running. We just need to make the proper database for your app.

First, let’s login to Postgres and list all of our current databases. We’ll be using the already-created user rails:

sudo -u rails psql -l

You should see a list of all your current database tables.

Next, in your project, open up the config file /config/database.yml and check your database name under production:. That’s the name we’ll be using to manually create our database in Postgres on our server. Feel free to change the name if you’d like. And don’t forget to update the username as well to rails.

Now back on your server, to create the new database name, run the following:

sudo -u rails createdb new_spina_app_production # This name will depend on your database.yml Production name

And finally, let’s set some environmental variables on your server for your app to use for security purposes (these are the ENV['NEW_SPINA_APP_DATABASE_PASSWORD'] inputs you see sprinkled throughout your app). I put mine in etc/environments. You can edit this file via nano, an FTP client, or some other method. It doesn’t really matter.

You’ll want to set two variables, SECRET_KEY_BASE and PRODUCTION_DATABASE_PASSWORD (this one’s name will vary on your database.yml config file). My file looks like this:

PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games"
SECRET_KEY_BASE="really_long_hash_here"
NEW_SPINA_APP_DATABASE_PASSWORD="password_you_wrote_down_earlier_from_.digitalocean.passwords"

Save and you’re all set to deploy!

4.3. Push your app

Next, push your local project code to GitHub and follow the steps outlined in my previous tutorial to setup Capistrano.

If you run into any issues, most of the time the output errors will give you enough info to solve it. If you have any really tough issues, feel free to drop me a line and I’m happy to try and help.

4.4. Database setup for Spina

One thing that is still lacking is that our Production database is missing the seed data that Spina normally creates with the rails g spina:install command. I’ve never tried this method, but in theory you can simply jump into the rails console on your server and re-run the Spina setup script from your app directory. Or create a extra part of the Capistrano script to seed the database for the initial run.

However, it’s so few table rows, I typically just use TablePlus to update the database manually myself. You only have to do it this one time and you’re set. Just compare the two databases (local and server) and copy the lines that are missing.

4.5: Done!

After all that, you should be setup and ready to use Spina! Now whenever you want to deploy a new update, simply run cap production deploy from your local project terminal and you’re all set.

Happy deployments!