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.
To avoid this tutorial becoming too long, I'm going to make some basic assumptions:
brewhas a painless method to install and setup (
brew install postgresql)
Let’s get started!
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
Spina v1.1.3 is broken for any Rails version above 220.127.116.11.
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', '18.104.22.168'" >> 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 22.214.171.124) 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', '>= 126.96.36.199' line (somewhere towards the top) to the following:
gem 'rails', '188.8.131.52'
Then finish it off by running the final command in your Terminal:
Phew, all done.
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:
Navigate your favorite browser to
localhost:3000 and you should see the Rails welcome page.
A very helpful tool I use for database management is TablePlus. It's handled every type of database I've thrown at it with ease and it's invaluable for my workflow.
Next, let’s add Spina. Open up your
Gemfile and add the following:
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 when you try to open up the admin dashboard in your browser, it just hangs and loads indefinitely, check your terminal's output. If you're getting a lot of SASS warnings/errors, you're probably using and older version of Spina. See above for the fix.
If you get a Sprockets error about manifest.js, just add this line to
//= link default/application.css and restart your server.
If you can see the Homepage in both the Spina admin dashboard and on
localhost:3000, you’re all set!
I’m not going to go into all the parts of Spina, but enough to get your footing.
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
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.
By default, Rails 6 uses Webpacker, and therefore so does Spina. Files are located in
The Spina documentation does a good job breaking down how to add a new page.
One trick I have learned is that if after restarting the server you don't see your "undeletable" pages (or Spina config changes in general), navigate to Preferences within the Spina Admin dashboard and click Styling. Then click "Save Settings" in the upper-right and it will force Spina to refresh itself and the new permanent pages will appear.
Navigate to Digital Ocean and create a new droplet with a Ruby on Rails image.
If you enjoy this tutorial and don't have a Digital Ocean account already, consider using this referral link. You get $10 and I get $10. It's a win-win.
As of this writing, it’s using
Rails 184.108.40.206, 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.
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:
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
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
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,
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"
To get your secret key above, just run
rake secret from your local project terminal.
Save and you’re all set to deploy!
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.
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.
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.