Getting Started with Ruby on Rails on Flightcontrol
This tutorial takes you through the process of deploying a Ruby on Rails web application to Amazon Web Services (AWS) with Flightcontrol. If you don't have a Rails application to deploy yet, you can visit our Create a Rails Application guide.
At the end of the tutorial, you will have a Rails web application running on AWS, and you will have learned how to use Flightcontrol to deploy your own Rails applications.
Important Database Note
You can't use SQLite as your database with Flightcontrol, because it's not supported on Amazon's Relational Database Service (RDS). It's a good idea to use the same database for local development and cloud deployment, so we recommend using Postgres (or MySQL or MariaDB) for both.
Using your GitHub Repository
Flightcontrol works with GitHub repositories to deploy your code base.
Your repository can be either private or public for Flightcontrol to work. If you have control over the repository, Flightcontrol can listen for changes to your repository and automatically deploy your application when you push new code. Public open source repositories are also supported, but you would need to trigger manual deployments.
We will need to authorize the Flightcontrol GitHub app to access this repository before we can deploy it.
Creating a Project on Flightcontrol
If you haven't already created a Flightcontrol account, you can do so at the Flightcontrol Dashboard (opens in a new tab).
Now that you have a Flightcontrol account, you can create a new project. Flightcontrol projects represent a single application or set of related applications that you want to deploy to AWS. Each project can have multiple environments, such as staging or production. Each environment can then have one or more services, such as a web application or a database.
To create a new project, click the "Projects" tab in the left hand sidebar. If you don't have any projects yet, Flightcontrol will show you the form to create one. If you do have an existing project or projects, click the "New Project" button.
For a new account, you will see the following form:
If you haven't connected your Flightcontrol account to GitHub yet, let's do that now. Click the "Continue with GitHub" button and start the connection process.
Follow our guide on Connecting Flightcontrol to GitHub to walk you through the necessary steps.
Once you have GitHub connected, instead of the above screen, you'll see a list of all of the GitHub repositories that the Flightcontrol Ops app can access.
Click the "Next" button to continue.
New users will see the following screen:
Choose a repository to continue.
Preparing for Launch
The next screen sets your Flightcontrol project up for deployment.
You have the choice of using the Dashboard (also called the GUI) for an interactive configuration, or using a
flightcontrol.json file for an infrastructure-as-code configuration.
We're going to use the GUI in this tutorial.
When it comes to an environment - you can choose to use the environments that make sense for your project deployment.
For this tutorial, we only need one environment, so we'll choose "Production".
We will configure our services individually and not use a preset configuration.
Configuring Services for Flightcontrol
At the bottom of the screen, there are choices for individual services to configure. Our Rails application is pretty simple - we only need a web server and a database.
Let's start with the database.
Click the "Add Database" button under "Services."
Setting up the Postgres Database with RDS
When it comes to databases, Flightcontrol supports Postgres, MariaDB, and MySQL through Amazon's Relational Database Service (RDS).
For this example, we will use Postgres. It is important to note that RDS does not support SQLite, so if you are using SQLite as your development database with Rails, you will need to choose one of the supported databases for your production environment.
In general, it's best to use the same database for development and production. This will help you avoid bugs that only occur when deploying to production.
For the purpose of this tutorial, the default settings for the database are fine. Make sure you have Postgres selected, and choose an inexpensive database tier.
Next, we'll add the web server.
Setting up the Rails Application with Fargate
Click the "Add Web Server (Fargate)" button under "Services".
Another service configuration screen will open up, but in this case, we will need to modify some of the defaults.
In particular, two things need to be changed:
- The name - this can be "Rails" or whatever you want to call the web server
- The build command - we need to run database migrations as part of the build phase
Change the build command to
bundle exec rails db:migrate && bundle exec rake assets:precompile
The last step for a successful Rails deployment is to set up the environment variables.
These environment variables are for an entire Flightcontrol environment, so they are shared between the database service and the web server service.
Your Rails application needs at least two environment variables to run properly:
RAILS_MASTER_KEY- Every Rails application will have a different master key for encrypting secrets.
RAILS_ENV- This should be set to
productionfor your Rails site to work on AWS. If you've set up other environments in your
config/environmentsfile such as
staging, you could use those.
You can find the Environment variables section at the bottom of the Flightcontrol enviroment page, below the services.
There is one special case if you are running MySQL as your database. See the Database URL section below for more details.
Rails Master Key
When you create a new Rails application, the
rails tool will generate a
config/master.key file for you. The contents of this file are used to encrypt secrets in your
config/credentials.yml.enc file. The
config/master.key file is not (and should not be) checked into source control (due to a rule in the
.gitignore file), and you will need to provide the value stored in this file to Flightcontrol as an environment variable. This would hold true for any production deployment for your Rails application.
You will need to manually set the
RAILS_ENV environment variable to
production for your Rails application to work properly with Flightcontrol.
In most cases (Postgres and MariaDB), Flightcontrol will automatically set the
DATABASE_URL environment variable for you.
However, if you are using a MySQL database, you will need to set the
DATABASE_URL environment variable manually. The reason for this is that the URL provided by RDS is in the format
mysql://, and Rails expects the URL to be in the format
mysql2://. Rails uses the first part of the URL, the scheme, to determine which database adapter to use. The
mysql2 adapter is the one that Rails uses for MySQL databases.
You will need to copy the value of the database URL from AWS Parameter Store, and then add
2 to the scheme at the beginning of the URL. For example, if the database URL is
mysql://, you will need to change it to
Errors with Deployment
If you run into any errors during the deployment process, you can check the build or deploy logs for the service that failed to deploy. You can find the logs by clicking on the Flightcontrol environment page.
The most common error you will see is that the health check failed. Double check that these configuration options are all in place:
- RAILS_ENV set to
- RAILS_MASTER_KEY set to the value of your Rails application's master key - in the
- Web Server Service build command set to
bundle exec rails db:migrate && bundle exec rake assets:precompile
If you're still having troubles, reach out to us for support please get in touch with us in our Discord Channel (opens in a new tab)! We're very happy to help, and to get you up and running on Flightcontrol.
Click the "Create Project" button after setting up your environment variables to start the deployment process.
If all goes well, Flightcontrol will deploy both services to AWS, and you will have a functioning Rails application on a publicly accessible URL!
This process can take between 10-20 minutes to finish the initial deployment.
Subsequent deployments are much faster. You can try this out by making a change to your Rails application and pushing it to GitHub. Flightcontrol will automatically detect the change on your
main branch and deploy it to your environment.