This post explores how to deploy your first [Solidus](https://github.com/solidusio/solidus) application ( the best eCommerce framework available in Ruby land) to [DigitalOcean](https://www.digitalocean.com/) (one of the top Infrastructure as a service provider that puts the developers at the center). You will use the services provided by DigitalOcean, like [Droplets](https://www.digitalocean.com/products/droplets/) and [Managed Databases](https://www.digitalocean.com/products/managed-databases/). This post is entry-level, you don’t need to be an experienced software developer to follow this. We are going to follow a step by step approach with lots of screenshots, and code snippets. So without further ado, let’s get started!

## Solidus

The first step is to create a Solidus application, to do that you can use the Solidus guide as reference.

If you prefer to just get started we have created a repository on Github ready to use, you can find it here.

On your local machine the application should look like this:

![Solidus homepage on localhost](https://cdn.sanity.io/images/kqgmf0g2/production/0b961debfd291b1bd0e38ac5abfc3d677cc760b7-2872x2104.jpg?fit=clip)

By the end of this post, you’ll be able to see this very same page online.

## DigitalOcean

Now it’s time to prepare the deployment environment on [DigitalOcean](https://www.digitalocean.com/). DigitalOcean is an Infrastructure as a service provider, this means that you can rent the infrastructure we need for our application from DigitalOcean with just a click.

To be more specific we are going to need two main components for our application:

* A server to host our code.

* A database to keep our data safe.

DigitalOcean has two services that are perfect for our needs:

* [Droplet](https://www.digitalocean.com/products/droplets/): an easy, fast, and flexible compute unit. You can imagine this to be a small server that you can use as you want.

* [Managed Databases](https://www.digitalocean.com/products/managed-databases/): a worry-free database hosting. You can imagine this to be a database ready to use, you don’t have to worry about installation and maintenance.

## Create the infrastructure

We are now going to create all the infrastructure we need on DigitalOcean.

First of all, you need to go to the [DigitalOcean homepage](https://www.digitalocean.com/) and sign in, or sign up if you don’t already have an account.

## Create the Database

Now that you are logged in, you are going to create the database.

We are doing this first because it’s your new database it’s going to take a while to become available, so we can work on other stuff while we wait for this to be ready.

From the homepage, you have to go to the `Databases` section (arrow 1). On the `Databases` sections, you need to click on `Create a Database Cluster` (arrow 2).

![Solidus dashboard on database section](https://cdn.sanity.io/images/kqgmf0g2/production/1c7c3e536b8901b4ca74b9c61aa62d9efb8bb5a2-2978x2072.jpg?fit=clip)

You can leave all the default values on the creation form, just scroll to the bottom of the page and click on `Create a Database Cluster`.

Note that DigitalOcean will create a default database inside your installation with a default admin user inside it. For this tutorial, we are going to use this database and user. In a real-world scenario I would suggest the creation of a custom database with its own admin user to improve the security of the system. You can do that through the database management UI.

Once created you will see the database management UI, you can skip the getting started section.

![Solidus dashboard on database section, created database](https://cdn.sanity.io/images/kqgmf0g2/production/15d7d19abed14c5dd50f5da0156e408b0498c569-2978x2072.jpg?fit=clip)

In the image, you can see the database management UI. Please note 2 things, pointed by the arrows in the image:

* Arrow 1: The credentials for your database, we are going to need them to configure our application.

* Arrow 2: At the moment your database can receive connections from all the internet, this is not ideal from a security point of view. We are going to fix this later.

Now your database is provisioning, while we wait for it to be ready we can create our server.

### Small note on DigitalOcean Managed Databases

The service [Managed Databases](https://www.digitalocean.com/products/managed-databases/) creates a cluster of databases for you. For this tutorial, you don’t need more than 1 database, but for a production application maybe you can consider creating a cluster with more than 1 database to be protected against outage, and to improve your disaster recovery capabilities.

You can read more about this on their [documentation](https://www.digitalocean.com/docs/databases/).

Create the Server
Now we are going to create our server, to do this you will use the [DigitalOcean Droplet](https://www.digitalocean.com/products/droplets/) service.

From the homepage, you have to go to the `Droplets` section inside it click on the `Create Droplet` button.

You can leave all the default values selected inside the form, you are going to use an Ubuntu image for the server. You need to add an ssh key during this process, the UI will guide you through the steps needed to do that.

Once created you will see the Droplet management UI.

![Solidus dashboard on droplet section, with a droplet created](https://cdn.sanity.io/images/kqgmf0g2/production/5dbd2fc47b45df83cba156f7da4e1a4bb4621aac-2978x2072.jpg?fit=clip)

## Let’s secure our database access

Now that you have created the server we can secure our database. We want the database to accept connections only from your newly created Droplet.

You have to take note of your Droplet’s name, it will look something like this `ubuntu-s-1vcpu-1gb-fra1-01`, you can find this on the Droplet management UI.

Now head back to the database management UI, from there:

* Click on `Settings`. (Arrow 1)

* Under `Trusted sources` put the name of your Droplet inside the autocomplete field. (Arrow 2)

* Click on `Save`. (Arrow 3)

![Solidus dashboard on database section, under the settings tab](https://cdn.sanity.io/images/kqgmf0g2/production/58d5001849f4d14ce44390b51887a6fefbcba122-3036x2072.jpg?fit=clip)

Now the only connections accepted by your database are the ones coming from your Droplet.

## Configure the Droplet

Now that the infrastructure is up and running we have to install the application on the server.

Your [Droplet](https://www.digitalocean.com/products/droplets/) is just a plain server running Ubuntu, to run your application on it you need to:

* Make sure that all the packages installed on the Droplet are updated.

* Install all the dependencies needed to run the application.

* Clone the application repo on the server.

* Configure the environment variables needed by the application.

* Setup the application’s server and database.

* And finally run the application.

It’s sound like a lot to do, but you’ll see that it’s easier that it looks like.

### Login inside the Droplet

To work on the Droplet you need to connect to it, that’s exactly why you added an ssh key during the configuration.

To login inside the droplet you can run the following command:

```
ssh root@<YOUR DROPLET IP ADDRESS>
```

You can find your Droplet IP address on the Droplets management UI section of the [DigitalOcean](https://www.digitalocean.com/) dashboard.

### Updating Droplet packages

The Droplet is just a plain server with an Ubuntu distribution installed on it, to update all the packages on it you can launch the following command:

```
apt update && apt upgrade -y
```

This will make sure that the system is updated, keeping you server updated it’s a good practice, and can help your system to stay secure.

### Install all the packages needed

You now have to install all the packages necessary to run Ruby and Ruby on Rails on the system.

There are quite a bit of packages needed, you can copy and paste the command below to install all of them:

```
apt-get install git-core zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev imagemagick nodejs ruby npm ruby-dev libpq-dev -y && npm install -g yarn
```

Now that all the packaged are installed you can install [Bundler](https://bundler.io/) and [Rails](https://rubyonrails.org/), to do that run:

```
gem install bundler rails
```

To check if everything is been installed correctly you can run the commands bellow, you should see a version number for every tool installed:

```
ruby -v
bundle -v
rails -v
node -v
yarn --version
```

### Clone the application repository

Now you are ready to clone the application inside the server. If the repo is public you can clone it using HTTPS. If it’s private you have to generate an ssh key for the Droplet, and add it to GitHub (or the repository provider that you are using).

For a production application, I’ll suggest configuring a dedicated ssh key for your Droplet, and use it to clone the repository.

For example, if you are using our public repository you can run this command:

```
git clone https://github.com/nebulab/digitalocean-solidus-demo.git
```

### Set the environment variables

We configured our example application to use environment variables to connect with the database, you can see the configuration on the [repository](https://github.com/nebulab/digitalocean-solidus-demo/blob/master/config/database.yml).

As you can see from the configuration file we need to set 5 environment variables:

```
 DATABASE_HOST
 DATABASE_PORT
 DATABASE_NAME
 DATABASE_USERNAME
 DATABASE_PASSWORD
```

Do you remember when earlier I talked about database credentials created by DigitalOcean? Now it’s time to use them.

You can add all the variables to our Droplet environment running the following command, remember to replace the placeholder with the information provided to you by DigitalOcean:

```
echo 'export DATABASE_HOST="<your_digitalocean_database_host>"' >> ~/.bashrc
echo 'export DATABASE_PORT=<your_digitalocean_database_port>' >> ~/.bashrc
echo 'export DATABASE_NAME="<your_digitalocean_database_database>"' >> ~/.bashrc
echo 'export DATABASE_USERNAME="<your_digitalocean_database_username>"' >> ~/.bashrc
echo 'export DATABASE_PASSWORD="<your_digitalocean_database_password>"' >> ~/.bashrc
```

You also have to set the variables to tell Ruby on Rails to treat this server as a production environment, and Puma to expose the application using the default HTTP port:

```
echo 'export RAILS_ENV="production"' >> ~/.bashrc
echo 'export PORT=80' >> ~/.bashrc
```

After this we have to reload our shell, you can logout and login again inside the Droplet, or you can run:

```
source ~/.bashrc
```

To verify that the variables are set correctly run:

```
echo $DATABASE_HOST
echo $DATABASE_PORT
echo $DATABASE_NAME
echo $DATABASE_USERNAME
echo $DATABASE_PASSWORD
```

You should see all you database information.

Setup our application
We have almost done, now you have to go inside the directory where your repository is cloned.

From there you should install all the gems needed, to do that just run:

```
bundle && yarn install --check-files
```

This can take a while, you can go and grab yourself something to drink because you have done a lot of work and you deserve it.

Last, but not least, you have to compile the assets. To do that you can run the command:

```
bundle exec rake assets:clobber && bundle exec rake assets:precompile
```

### Adding security and setting up the database

Our application needs a secret key to run. How to manage the secret key correctly, and secrets in general, is outside the scope of this article. You can find more on the official [Ruby on Rails Guide](https://guides.rubyonrails.org/security.html).

To generate a secret key for your application you can run:

```
EDITOR="nano --wait" bin/rails credentials:edit
```

Now you need to load the database schema of the application, and setup the seed data inside it. To do that run the following command:

```
bundle exec rails db:schema:load db:seed
```

Don’t worry if it takes a while, you are loading a lot of data inside the database, and you are using the cheapest option offered by DigitalOcean it’s normal. Just relax and get ready for the last step.

### Launch the application

Everything is finally ready, you can launch you application with the command:

```
bundle exec rails s
````

This will launch [Puma](https://github.com/puma/puma), and expose your application to the internet. From the Droplet management UI copy your Droplet IP address, use your browser to navigate to it, and you should see your application up and running!

![Solidus homepage online](https://cdn.sanity.io/images/kqgmf0g2/production/dd129e0140f09b2c7cd80eafe1166749bd3715cc-2872x2104.jpg?fit=clip)

### Road to production

Your application is finally online, congratulations! Take a moment to appreciate all the things you have done to accomplish this:

* You started from a local working application.

* Bootstrapped your server and database.

* Configured your server.

* Configured your app.

* Launched the app and made it available to the internet.

This is great, but it’s just a starting point. To be used in a real production environment our deployment needs some more work.

In the following sections we introduce the improvements needed to make our deployment production-ready.

### Improving the Droplet configuration

If you want to use your Droplet for production you need to improve the configuration to make it secure and stable for a real-world scenario. You have to:

* Setup a firewall.

* Setup a reverse proxy, using tools like [NGINX](https://www.nginx.com/).

* Create a user for the deploy, instead of using the root user.

* Add SSL certificate to enable HTTPS for the application, using tools like [Certbot](https://certbot.eff.org/).

* Isolate the installation of Ruby, and the bundle gems with tools like [Rbenv](https://github.com/rbenv/rbenv)

* Use a proper key to store the secrets.

* Set proper credentials for the Solidus store’s admin user.

### Automate all the things

Doing all these installation steps by hand is boring, and error-prone. You can avoid it using a combination of tools to automate the creation, provisioning of the server, and deployment of your application.

One tool that you can look at for deploy automation is [Capistrano](https://capistranorb.com/), it’s quite popular inside the Ruby on Rails community.

You can integrate Capistrano with a CI/CD tool like [CircleCI](https://circleci.com/) to enable the continuous deployment of your code.

For more advanced use cases you can use [Terraform](https://registry.terraform.io/providers/digitalocean/digitalocean/latest/docs) to implement your infrastructure as code, and [Ansible](https://www.ansible.com/) to automate the configuration of your server.

With Terraform you can automate the creation of the infrastructure needed by your application, the Droplet and database. With Ansible you can automatically install all the packages you need on your Droplet.

### Uploading files to an external storage

Right now the application is storing all the static files of the Solidus store on the local hard disk, this is not ideal because if the Droplet goes down you risk losing all the data.

To avoid this you can use external static file storage services, for example DigitalOcean provides [Spaces](https://www.digitalocean.com/products/spaces/) an S3-compatible object storage with a built-in CDN that makes scaling easy, reliable, and affordable.

## That’s all

I hope you liked this tutorial, and that it was useful to kick-off your journey with [Solidus](https://github.com/solidusio/solidus) and [DigitalOcean](https://www.digitalocean.com/).

If you enjoyed this tutorial please share it with the world, if you want to know more leave a comment and start a conversation.

Deploy your first Solidus application to Digital Ocean

I love coding, and recently I started enjoying some devops too. I always preferred
writing code more than configuring Apache, servers and services, so I feel I'm
a bit late to the devops and cloud computing party... but better late than never!

This post was born from the idea of mixing together [Solidus][Solidus] (the
best ecommerce available in Ruby land) and [Amazon AWS][AWS] (probably the most
successful and advanced cloud computing platform) using [Opsworks][Opsworks],
[Chef][Chef] and the gem [opworks ruby][opsworks_ruby].
I'm going to follow a step by step process with lots of screenshots, hoping
this will remain relevant in the next future.  Without further ado, let's get
started!

## Solidus

The first step is generating a Solidus application that can run locally.

Create a new Rails app (use the `-D` flag and set the RDBMS you want to use with
[Amazon RDS][RDS], I used MySQL for this demo), add Solidus gems and generate the
Solidus boilerplate as per Solidus [README][Solidus].

After running all commands your development environment should be ready for a ride.
Start the server, navigate to `localhost:3000` and you should see your store
homepage with all Rails branded gadgets.

By the end of this post we'll be able see this very same page hosted in the cloud:

![](https://cdn.sanity.io/images/kqgmf0g2/production/274c8495c9303b8851751b3523a4d24efd6c66e9-2070x1766.jpg?fit=clip)

Create a new repository on Github and push your code, we're going to need it later...
or you can use [my repository][demo].

## Opsworks ruby

Now it’s time to setup the deployment environment. First, in order to deploy a
Rails app with Opsworks you need a proper Chef cookbook. A Chef cookbook is a
collection of recipes, written in Ruby, that contain information on resources
(programs, services etc.) that need to be installed, changed, and run on a node.

For our needs you can pick the [one I wrote][cookbook] (check git history for changes)
or you can create a new one following the instructions in the [README][cookbook].

This cookbook is based on `opsworks-ruby`, a set of Chef recipes that completely
automate the provisioning and deployment to AWS of the most popular Ruby web frameworks
including Rails, Hanami and Padrino.

![](https://cdn.sanity.io/images/kqgmf0g2/production/f5b07d26bd9d4350bf4f3ea4ae6fc2774744d4a1-2218x1392.jpg?fit=clip)

Once you have the cookbook ready, you need to upload the file `opsworks_cookbook.tar.gz`
to [Amazon S3][S3].
For the sake of simplicity, let’s make the file public - it may be left private as well,
but then you’d need to provide access credentials when you create the app on OpsWorks.

## Opsworks AWS

### Create the stack
Let's now start configuring Opsworks on AWS. First, we need to create a new Opsworks Chef
stack. A stack is a collection of separate Amazon services (layers) that operate together
in order to properly run your application: server applications, databases, load balancers
and so on. Choose the `Opsworks Stacks` option from AWS Opsworks homepage:

![opsworks chef automate](https://cdn.sanity.io/images/kqgmf0g2/production/0263d09dd393d0ac05bb6edf8de7d223d3bb17f1-2014x1574.jpg?fit=clip)

Click `Add your first stack` in the following page and you should eventually be able
to start configuring your stack, just follow the screenshots below.
Make sure the flag `Use custom Chef cookbooks` is set to `true`, choose `S3 Archive` as repository type and paste
the right cookbook file URL in `Repository URL`:

![](https://cdn.sanity.io/images/kqgmf0g2/production/0ee2a2fbfe4f34e0fd8e73137d4fa49b7a53f64c-2230x1874.jpg?fit=clip)

### Add the Rails layer

After being redirected to a new page with a success message, you can now click on `Add a layer` and give
the layer a name and a short name (I used `Rails`):

![](https://cdn.sanity.io/images/kqgmf0g2/production/de529d71022100d32e404653dccf0d06ed395c3c-2092x1170.jpg?fit=clip)

### Rails layer recipes

After that we're going to add our recipes to it... remember to click the blue button `+` every time you add a recipe and
eventually `Save` when you're done:

![add recipes to rails layer](https://cdn.sanity.io/images/kqgmf0g2/production/ee2a812a1843e7e223dbc52dba507506be0f69d0-2092x1810.jpg?fit=clip)

### Add the Rails app

Let's now add the actual Rails app to the stack. Click on `Apps` on the navigation sidebar, and fill in the
data by following the screenshot example. Put the link to your github app source code in the field
`Repository URL`. Click `Add App` and you're done:

![Add the Rails app](https://cdn.sanity.io/images/kqgmf0g2/production/0ecb46831dc327a787e11c98527d53976f6aacee-2230x1866.jpg?fit=clip)

### Add an app instance

Now click on `Instances` on the navigation bar. Then click on `Add an instance` and fill in the
form as follows:

![add a new instance](https://cdn.sanity.io/images/kqgmf0g2/production/8039b29aa23b39d850988fbffda9a87196f49e03-2236x1480.jpg?fit=clip)

I'm using a `t2.micro` instance here, please choose wisely on your side as larger Amazon VMs can
become expensive!


You can now start the instance, Opsworks will attempt to deploy automatically:

![](https://cdn.sanity.io/images/kqgmf0g2/production/8a7a8ef86b6d0f45a2b5b2f45944a969ab809659-2236x1480.jpg?fit=clip)

We still have a lot of ground to cover, so don't be disappointed when the deploy fails.
Check the `failure` log and familarize yourself with it as you'll probably have to fix other issues
on your own in the future, besides the ones we're going to tackle today:

![](https://cdn.sanity.io/images/kqgmf0g2/production/6f9fe05f90bac9653eea5ed4411acc2fb0c07a70-2218x1392.jpg?fit=clip)

![](https://cdn.sanity.io/images/kqgmf0g2/production/c933e37ee4b64fbcf672f69029fc2a2de3961687-1608x250.jpg?fit=clip)

## Add the database

Let's add the database layer. Visit Amazon RDS page and click on `Create Database`. Choose your
RDBMS system (I picked MySQL). Choose the `Free tier` option (again, playing around with AWS can
become quickly expensive) and choose a `DB instance identifier` name:

![](https://cdn.sanity.io/images/kqgmf0g2/production/574de6acdc8c6425fd1fc50cb9080e2d9b8b1b8c-2022x2493.jpg?fit=clip)

### Add database layer

Go back to Opsworks and add a database layer. You will see the newly created DB listed on the page.

![](https://cdn.sanity.io/images/kqgmf0g2/production/a4e9ec3e4e0891aa6be7d7ce923de61478ee750f-2128x1356.jpg?fit=clip)

After that, we still need to link the RDS database to the app:

![](https://cdn.sanity.io/images/kqgmf0g2/production/0351f3e9e86a607ad3cedb640b7f2c7eef2cec1f-2128x1356.jpg?fit=clip)

## Turning on the instance

Let's try to turn on the instance again... and again it will fail. This time the error is:

```
ArgumentError: Missing `secret_key_base` for 'production' environment, set this string with `rails credentials:edit`
```

Easy fix: visit the app edit page again, and add an ENV variable for the `secret_key_base`, like this:

![](https://cdn.sanity.io/images/kqgmf0g2/production/36749d2e3eb9e376716657c8447759c3bb67121b-2128x1356.jpg?fit=clip)

After this, turning the instance on will result in another error. The connection cannot be estabilished.
This is due to the different security groups of the Rails layer and RDS database instance.

Again, an easy fix. Visit the database edit page and update it. While there, make the database publicly
accessible so you will be able to load a database dump:

![](https://cdn.sanity.io/images/kqgmf0g2/production/cd880961cc48ea69aa26cdcb3b8671c52d711e1c-1800x1662.jpg?fit=clip)

If you try to turn the instance on, you will get the last error (hopefully!) we're going to see today:

```
Create the admin user (press enter for defaults).
Email [admin@example.com]:
STDERR: rake aborted!
NoMethodError: undefined method `strip' for nil:NilClass
```

This is due to the fact that the boot process tries to run Solidus setup, but as there's no shell for user
input the process fails. This can be easily fixed by setting ENV variables for `ADMIN_EMAIL` and `ADMIN_PASSWORD`,
but we're going to circumvent this issue, as this gives us the chance to see how to import DB data to RDS.

Check on your RDS database page the public URL for accessing it:

![](https://cdn.sanity.io/images/kqgmf0g2/production/9adfb61b44cd1e77f2e23ffa712141db74482914-2254x1758.jpg?fit=clip)

If you've never done this before, you need to add your SSH key to AWS in order to connect to the servers
using the terminal. Please follow the official [Amazon guide][aws-ssh] for completing this step.

Dump your local DB data with mysqldump on your HD, so we can load it on RDS via SSH. First check you can
access the database:

```
$ mysql -u admin -pSECRETPASSWORD -h solidus-db.cyb3dsv86rfu.eu-central-1.rds.amazonaws.com
mysql> show databases;
+--------------------+
| Database           |
+--------------------+
| information_schema |
| innodb             |
| mysql              |
| performance_schema |
| solidus-db         |
| sys                |
+--------------------+
6 rows in set (0,03 sec)
```

Now, load the dump:

```
$ mysql -u admin -pSECRETPASSWORD -h solidus-db.cyb3dsv86rfu.eu-central-1.rds.amazonaws.com solidus-db < development.sql
```
After it's done, it's time to start the instance for the last time:

![](https://cdn.sanity.io/images/kqgmf0g2/production/8fad4d63e3545fcefe601291b1a2d090e5459227-2128x1356.jpg?fit=clip)

When you click on the IP address you will be redirected to your Solidus website:

![](https://cdn.sanity.io/images/kqgmf0g2/production/7f0c14383966ea1b6359d66c5b7ff8004feeea7d-2210x1740.jpg?fit=clip)

And that's all folks! I know this is just a very basic Solidus installation, images are still hosted on the
filesystem and you probably want to host them on S3 or similar services, but hope you enjoyed this post and
the step by step process will guide other devs that are not (yet) comfortable with AWS in making their first
Solidus/Rails application deployment.


[Solidus]: https://github.com/solidusio/solidus
[AWS]: https://aws.amazon.com/
[Chef]: https://www.chef.io/
[Opsworks]: https://aws.amazon.com/opsworks/
[opsworks_ruby]: https://github.com/ajgon/opsworks_ruby/
[RDS]: https://aws.amazon.com/rds/
[cookbook]: https://github.com/nebulab/aws-solidus-demo-opsworks_cookbook
[S3]: https://aws.amazon.com/s3
[demo]: https://github.com/nebulab/aws-solidus-demo
[aws-ssh]: https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#how-to-generate-your-own-key-and-import-it-to-aws

Solidus deployment with Amazon AWS Opsworks

In this tutorial we'll show you how to deploy a [Solidus eCommerce][solidus] application
to Heroku, the most famous cloud platform.

Here are our requirements:

- [AWS S3 Account][aws_s3_account] with access_key and secret_key
- [Heroku account][heroku_account]
- Installed and configured [Heroku CLI][heroku_cli]
- Rails (version 5.0 was used to write this article)
- Git

### Install and configure your eCommerce locally

First of all, like you did a thousand times, create your new Rails application:

```sh
rails new my_ecommerce --database=postgresql
cd my_ecommerce
```

Initialize your project and make your first commit in Git:

```sh
git init
git add .
git commit -m 'Initial project'
```

In order to turn your simple application into an eCommerce, you now need to
install the Solidus gem. Simply add the following lines to your Gemfile:

```ruby
gem 'solidus', '~> 2.1.0'
gem 'solidus_auth_devise'
gem 'aws-sdk', '< 2.0'
```

Note that we are also specifying the `aws-sdk` gem; this is needed if we want to
use S3.
Edit your `config/database.yml` and add the database configuration:

```yml
default: &default
  adapter: postgresql
  pool: 5

development:
  <<: *default
  database: my_ecommerce_dev

test:
  <<: *default
  database: my_ecommerce_test
```

Install and run migrations on Solidus:

```sh
bundle
bundle exec rake db:create
bundle exec rails g spree:install
bundle exec rails g solidus:auth:install
bundle exec rake railties:install:migrations
bundle exec rake db:migrate
```

Run `bundle exec rails s` then go to
[http://localhost:3000](http://localhost:3000) and make sure you correctly
visualize the homepage.

### Configure Heroku

Ok, let's start running some commands on Heroku. Make sure you are already
logged in Heroku with the `heroku login` command. Then you can create your new
Heroku application with the following:

```sh
heroku apps:create my_ecommerce
```

This command creates a new application called `my_ecommerce` on Heroku. A new
remote repository named heroku (pointing to the new application) will also be
added to your git config.
You can check this with:

```sh
git remote -v
```

### Configure the production environment

Add the `heroku-postgresql` add-on to your Heroku application:

```sh
heroku addons:create heroku-postgresql
```

After adding the add-on you can see the new configuration environment with the
command:

```sh
heroku config
```

The above command should return something like this:

```sh
=== my_ecommerce Config Vars
DATABASE_URL: postgres://XXXX:yyyyy@ec2-1-2-3-4.compute.amazonaws.com:5432/zzzzz
```

The `DATABASE_URL` variable stores the location of the database. You can now add
the following lines to your `config/database.yml` under the production
environment settings:

```yml
production:
  <<: *default
  url: <%= ENV['DATABASE_URL'] %>
```

### Saving files on S3

Heroku uses an [Ephemeral filesystem][heroku_fs], which means that it doesn't
provide any sort of persistent storage for data. Your images would therefore be
removed after each deploy.
In order to bypass this limitation you'll need to use an external service (like
Amazon S3) to store your images.
Run the following commands to prepare the Heroku environment:

```sh
heroku config:add AWS_ACCESS_KEY_ID='YOUR_ACCESS_KEY'
heroku config:add AWS_SECRET_ACCESS_KEY='YOUR_SECRET_KEY'
heroku config:add S3_BUCKET_NAME='YOUR_BUCKET_NAME'
```

Add this configuration in `config/initializers/spree.rb`:

```rb
if Rails.env.production?
  attachment_config = {
    s3_credentials: {
      access_key_id:     ENV['AWS_ACCESS_KEY_ID'],
      secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'],
      bucket:            ENV['S3_BUCKET_NAME']
    },

    storage:        :s3,
    s3_headers:     { 'Cache-Control' => 'max-age=31557600' },
    s3_protocol:    'https',
    bucket:         ENV['S3_BUCKET_NAME'],
    url:            ':s3_domain_url',

    styles: {
      mini:     '48x48>',
      small:    '100x100>',
      product:  '240x240>',
      large:    '600x600>'
    },

    path:           '/:class/:id/:style/:basename.:extension',
    default_url:    'noimage/:style.png',
    default_style:  'product'
  }

  attachment_config.each do |key, value|
    Spree::Image.attachment_definitions[:attachment][key.to_sym] = value
  end
end
```

### Deploy Solidus to Heroku

Now commit and push your code to the Heroku repository:

```sh
git add .
git commit -m 'Configure Heroku Environment'
git push heroku master
```

If the `push` command runs without errors you'll see:

```sh
remote:
remote: Verifying deploy... done.
To https://git.heroku.com/my_ecommerce.git
 * [new branch]      master -> master
```

### Populate your remote database

Last but not least, you can now put your data in the database.
Heroku CLI helps you with the command `heroku run`, that runs rake tasks
on the deployed application.

Migrate the database and run the seed data:

```sh
heroku run rake db:migrate
heroku run rake db:seed
```

The seed process creates the default admin user and the basic configuration
needed to bootstrap your eCommerce and start selling on the Internet.

If you want to add [sample data][sample_data] you can run:

```sh
heroku run rake spree_sample:load
```

Now you can open your browser and enjoy your Solidus eCommerce by visiting
https://my_ecommerce.herokuapp.com or using the following Heroku CLI command:

```sh
heroku open
```

You can find the code used for this tutorial on this [repo][github_repo].

[github_repo]: https://github.com/nebulab/solidus-on-heroku
[aws_s3_account]: https://aws.amazon.com/s3/
[heroku_account]: https://signup.heroku.com
[heroku_cli]: https://devcenter.heroku.com/articles/heroku-cli
[heroku_fs]: https://devcenter.heroku.com/articles/dynos#ephemeral-filesystem
[sample_data]: https://github.com/solidusio/solidus/blob/master/sample/README.md
[solidus]: https://solidus.io/

Deploy Solidus to Heroku like a boss

It's been a while since we switched all our infrastructure from Apache2 + Passenger to Nginx + Unicorn and we've really been satisfied with such a choice.

Unicorn gives you tremendous geek power and responsibility. It may seem initially hard (it's so distant from that "php feeling" you get when working with Passenger) but once you unleash some Unicorn power, you can never go back.

One of the most amazing things you can do with Unicorn is monitor its behavior in depth with ease and peace of mind (read UNIX Signals). To monitor a Unicorn process you can use a multitude of tools: [bluepill](https://github.com/arya/bluepill), [god](https://github.com/mojombo/god/) and [monit](http://mmonit.com/monit/). The first two being Ruby applications while monit being a C application.

Since we read so many horror stories about Ruby memory leaking all over that great unicorn fur, we chose monit as our main monitoring solution (not that its syntax is so much more complex than Ruby's).

## Monitoring Unicorn
Unicorn's structure is simple and effective; it has a _"master process"_ which administers a number of _"worker processes"_ that actually serve HTTP requests. These worker processes are actually forked from the master process, this means (in a monitoring perspective) that we can not only monitor each worker individually but also the master process as a sum of resources used up by its workers.
There is a much more in-depth article (it's great and you should read it): [I like Unicorn because it's Unix](http://tomayko.com/writings/unicorn-is-unix).

We'll see the approach we use in each of our applications:

1. monitor the application as a whole via the unicorn master and alert if there is any status change;
2. monitor each worker process to gracefully kill any worker which is using up too much resources.

All the examples will refer to the _nebulab_ application.

### Master
Monitoring the unicorn master process is simple, we should already have everything in place by default. This is the required monit configuration (`/etc/monit/conf.d/nebulab.monitrc`):

```sh
check process nebulab with pidfile /var/run/unicorn/nebulab/pid
  start program "/etc/init.d/nebulab start"
  stop program "/etc/init.d/nebulab stop"
  if 5 restarts within 5 cycles then timeout
```

Monit will then make sure that this process is always running and will email us if anything happens to the process (i.e. it gets restarted without monit's consensus).
If you want to keep track of how much memory/cpu unicorn is using up as a whole, you can add some more triggers like so:

```sh
check process nebulab with pidfile /var/run/unicorn/nebulab/pid
  start program "/etc/init.d/nebulab start"
  stop program "/etc/init.d/nebulab stop"
  if 5 restarts within 5 cycles then timeout
  if totalcpu is greater than 50% for 2 cycles then alert
  if totalcpu is greater than 90% for 3 cycles then restart
  if totalmem is greater than 60% for 1 cycles then restart
```

but we usually don't use those since we have many more monit configurations that monitor the system as a hole.

### Workers
Monitoring the worker processes is a little bit more complicated, it requires a way of signaling a single worker that needs to shutdown after closing its last request. We also need to make monit aware of that process (we need a pid for each worker). This requires a unicorn configuration that is a bit more elaborate than the "default".

We begin by creating a pid for each worker. This can be done with the unicorn _after_fork_ hook:

```ruby
after_fork do |server, worker|
  # Create worker pids too
  child_pid = server.config[:pid].sub(/pid$/, "worker.#{worker.nr}.pid")
  system("echo #{Process.pid} > #{child_pid}")
end
```

This ensures that, immediately after the worker process has been forked, a pidfile named _worker.nr.pid_ is created (nr being the worker number).
Here is the complete configuration file:

```ruby
##
# Unicorn config at /etc/unicorn/nebulab.rb
# Managed by Chef - Local Changes will be Nuked from Orbit (just to be sure)
##

# What ports/sockets to listen on, and what options for them.
listen '/var/run/unicorn/nebulab/socket', :backlog => 100

working_directory '/var/www/nebulab/current'

# What the timeout for killing busy workers is, in seconds
timeout 60

# Whether the app should be pre-loaded
preload_app true

# How many worker processes
worker_processes 2

if GC.respond_to?(:copy_on_write_friendly=)
  GC.copy_on_write_friendly = true
end

before_exec do |server|
  ENV['BUNDLE_GEMFILE'] = "/var/www/nebulab/current/Gemfile"
end

# What to do before we fork a worker
before_fork do |server, worker|
  defined?(ActiveRecord::Base) && ActiveRecord::Base.connection.disconnect!

  system "test -x /opt/scripts/repair_permissions_nebulab.sh && /opt/scripts/repair_permissions_nebulab.sh"

  old_pid = "/var/run/unicorn/nebulab/pid.oldbin"
  if File.exists?(old_pid) && server.pid != old_pid
    begin
      Process.kill('QUIT', File.read(old_pid).to_i)
    rescue Errno::ENOENT, Errno::ESRCH
      # someone else did our job for us
    end
  end
end

# What to do after we fork a worker
after_fork do |server, worker|
  defined?(ActiveRecord::Base) && ActiveRecord::Base.establish_connection

  # Create worker pids too
  child_pid = server.config[:pid].sub(/pid$/, "worker.#{worker.nr}.pid")
  system("echo #{Process.pid} > #{child_pid}")
end

# Where to drop a pidfile
pid '/var/run/unicorn/nebulab/pid'

# Where stderr gets logged
stderr_path '/var/log/unicorn/nebulab/error.log'

# Where stdout gets logged
stdout_path '/var/log/unicorn/nebulab/output.log'

# The user/group to run unicorn as
user 'www-data', 'www-data'
```

We now need a way to signal each worker when to die... Since we already have an _init.d script_, will edit that to support single worker signaling. A unicorn worker can be gracefully killed by sending a `QUIT` signal, we can do it with the _init.d script_:

```sh
#!/bin/sh
set -e

# Include Bundler path
PATH=$PATH:/usr/local/bin

### Unicorn Variables ###
TIMEOUT=60
APP_ROOT=/var/www/nebulab/current
PID_PATH=/var/run/unicorn/nebulab
PID=$PID_PATH/pid
CMD="bundle exec unicorn -D -c /etc/unicorn/nebulab.rb -E production"
INIT_CONF=$APP_ROOT/config/init.conf

action="$1"
set -u

test -f "$INIT_CONF" && . $INIT_CONF

old_pid="$PID.oldbin"

cd $APP_ROOT || exit 1

sig () {
  test -s "$PID" && kill -$1 `cat $PID`
}

oldsig () {
  test -s $old_pid && kill -$1 `cat $old_pid`
}

workersig () {
  workerpid=$PID_PATH/worker.$2.pid
  test -s "$workerpid" && kill -$1 `cat $workerpid`
}

create_pid_path () {
  test -d $PID_PATH || ( mkdir -p $PID_PATH && chown www-data.www-data $PID_PATH )
}

case $action in
start)
  create_pid_path
  sig 0 && echo >&2 "Already running" && exit 0
  $CMD
;;
stop)
  sig QUIT && exit 0
  echo >&2 "Not running"
;;
force-stop)
  sig TERM && exit 0
  echo >&2 "Not running"
;;
restart|reload)
  sig HUP && echo reloaded OK && exit 0
  echo >&2 "Couldn't reload, starting '$CMD' instead"
  $CMD
;;
upgrade)
  sig USR2 && exit 0
  echo >&2 "Couldn't upgrade, starting '$CMD' instead"
  $CMD
;;
status)
  sig 0 && echo "running with pid `cat $PID`" && exit 0
  echo stopped && exit 1
;;
kill_worker)
  workersig QUIT $2 && exit 0
  echo >&2 "Worker not running"
;;
reopen-logs)
  sig USR1
;;
*)
  echo >&2 "Usage: $0 <start|stop|status|restart|upgrade|force-stop|reopen-logs|kill_worker>"
  exit 1
;;
esac
```

We added a `kill_worker` command to the init script that sends the `QUIT` signal so that we can kill a worker by running:

```sh
$ /etc/init.d/nebulab kill_worker nr
```

where nr is the number of the worker. This will give us a way of killing a worker without worrying about lost connections and the unicorn master process will make sure to spawn a brand new worker.

Now that we have the correct pieces in place, we can configure monit. We should have a configuration for each of the worker processes. The nebulab application will have two monit configurations (one for each worker). Below is the configuration for `worker 0`:

```sh
check process nebulab_worker_0 with pidfile /var/run/unicorn/nebulab/worker.0.pid
  alert root@localhost only on { pid }
  if changed pid 2 times within 60 cycles then alert
  if memory usage > 16% for 1 cycles then
    exec "/etc/init.d/nebulab kill_worker 0"
  if cpu is greater than 50% for 2 cycles then
    exec "/etc/init.d/nebulab kill_worker 0"
```

This will ensure that our worker will get gracefully killed if:

* it takes more than 16% memory for 30 seconds
* it takes more than 50% cpu for 1 minute

Since we expect the worker to be killed often, we don't want to be notified every time something happens to the workers:

```sh
alert root@localhost only on { pid }
if changed pid 2 times within 60 cycles then alert
```

This will notify us only of pid changes (when the worker is killed and a new one is spawned) and  we'll be notified only when the pid is changed at least twice in 30 minutes. There is no need to spam our inbox, the more mail we receive, the more we risk disregarding a serious problem as "just another of monit's alerts".
Instead, by doing so, we only get an email when a worker goes crazy for some reason and keeps eating up cpu/memory, thus being continuously restarted.

Once you have everything in place you should be able to restart monit and wait for the magic to happen... You can keep track of what monit is doing with the `monit status` command.

## Additional Resources
* [Unicorn signals](http://unicorn.bogomips.org/SIGNALS.html)
* [Monit documentation](http://mmonit.com/monit/documentation/monit.html)
* Other articles on the matter: [1](http://www.stopdropandrew.com/2010/06/01/where-unicorns-go-to-die-watching-unicorn-workers-with-monit.html), [2](http://shapeshed.com/managing-unicorn-workers-with-monit/)

The Nebulab

Deploy your first Solidus application to Digital Ocean

Solidus deployment with Amazon AWS Opsworks

Deploy Solidus to Heroku like a boss

Monitoring Unicorn with Monit