You can use Northflank templates and release flows to easily initialise your project and manage new releases with migrations.
Ruby on Rails, like many frameworks, uses the Active Record pattern to manage data, which means schemas and operations can all be managed from within the application code itself. This also allows it to easily work with different databases out of the box, including SQLite, MySQL, and PostgreSQL.
In this guide you will learn how to build and deploy a simple Ruby on Rails application on Northflank, with a Postgres database addon, and manage releases with migrations. This guide will cover:
- An overview of the example template
- How to release new versions of the application and run migrations using pipelines and release flows
You can copy this template to get started, or clone this repository ADD LINK and edit the template to use the URL to your cloned repository instead. To do this, find the BuildService node and change the projectUrl value in the vcsData object to your own repository's URL.
Or, if you'd prefer, clone the repository and follow the quick start guide in the readme to create a project from scratch.
Please note: this guide assumes you have run the default template and are deploying from the Northflank Examples repository. As you won't be able to merge PRs in this repository, this guide uses the update-schema branch for the new release instead of the main branch.
This template consists of:
- A Postgres database Addon to use with the Rails application
- A secret group to provide the connection details from the Addon to the Rails application deployments and jobs. This secret group also set aliases for pgAdmin, so you only need to add the required secrets and secret file to deploy it.
- A build service to build branches and pull requests from the Rails repository
- A build node to build the branch
main - A condition node to check the build is successful, using the reference
rubyBuild - A deployment service to serve the built Rails application
- A condition node to check the deployment service is running, using the reference
rubyDeployment - An action node to execute a command in the service to run the initial migration:
bin/rails db:migrate - An action node to restart the deployment after the migration
- A manual job node to create a job to run future migration tasks in a job
To use this template, click the link and select the account you want to use the template in. You can edit details including the template name, project name, region, and enable GitOps to save to a git repository. You can also run the template automatically when the it is updated, but leave this unselected for now. Save and run the template to create a new project with the specified resources. Take some time to review the template run and check out the resources created in your new project. Learn more about using templates on Northflank.
Let's take a closer look at some of the resources in the project:
This service is configured to build the branch main and all pull requests from this repository ADD LINK using the recommended buildpack stack (heroku/builder-classic:22). CI is enabled, so any new commits to these branches, as well as any pull request, will be built automatically.
The job is configured to also deploy the latest build from the branch main, using the Northflank build service as the source.
The buildpack runtime mode is configured to run using the custom process: release from the Procfile, which runs the command bundle exec rails db:migrate.
This deployment service uses the build service as the source for images to deploy. CD is enabled, so it will deploy the latest build from the branch main.
As the repository has a Procfile the web process will be run by default, which is the command bundle exec rails server to start the server.
Finally, port 3000 is exposed as a public HTTP port to make the application accessible via a Northflank-generated domain name.
The deployment automatically inherits the connection details for the Postgres addon via the secret group.
After you have run the template open the project Northflank Rails migration example and find the deployment service Rails deployment. Open the link to the generated domain name to see the application, which should display the title Articles with a link to /articles/new titled New Article.
Click New Article, enter a title and body text, and click Create Article. You should see your article title and body, and if you return to the web application's root page, it should appear in the list of articles.
In our example repository, the update-schema branch contains a new feature that we want to release, which requires a migration to be run to update the Postgres database, otherwise the application will crash.
The new feature adds the author field to articles, and the migration was generated after updating the application code by running the command bin/rails generate migration AddAuthorToArticle author:string on the local development machine.
This created the migration file in the repository directory db/migrate, and as it's the most recent migration file it will be run when the command bin/rails db:migrate is called. The repository Procfile contains the release command bundle exec rails db:migrate to ensure that the required gems are installed by the bundler before calling the command.
In the service Rails deployment turn off continuous deployment (CD), as this would automatically deploy the latest builds from the linked branch (main). As CI is enabled in the build service for this branch, any new commits to the branch would be built and deployed automatically, without running any migrations.
To release a new version of the application with a migration we want to complete the following tasks:
- Back up the database, in case we need to roll back
- Deploy the built release to the migration job and run the migration
- If successful, deploy the new release to the deployment service
You can create a simple [release flow] to automate this release and migration process. To do this, you'll need to create a pipeline and add the project resources to a pipeline stage.
In the project open the pipelines page and create a new pipeline called Rails application. Click the plus + in the production stage of the pipeline, and add the deployment service Rails deployment, job migrate db, and the database addon postgres to the pipeline stage. This will make them available in the production stage when creating a release flow.
Click + add release flow above the projection stage to begin creating a release flow. Select get started with visual editor or click the visual tab to create a release flow with the visual editor. You can now click and drag nodes from the list on the right into the workflow in the editor on the left.
ADD VIDEO/GIF
First, drag a run backup node into the editor and click on it to open the node editor. Select postgres from the addon dropdown selection, and disk backup as the backup type. If you don't see the postgres addon in the dropdown menu, exit the release flow editor and ensure it is added to the pipeline stage. Finally, select wait for completion so that the backup is finished before running the migration, and save node to finish.
Now, drag a deploy build node underneath the run backup node. It will be added to the workflow with an arrow from the first node to the second, indicating it will be run after it in sequence. You can click and drag nodes to re-order them.
Click the deploy build node to configure it. Select the Rails builder as the build service, select the update-schema branch and latest for the build, and then choose the migrate db job as the target. Save node to continue.
This will deploy the build of the most recent commit to the update-schema branch to the migrate db job, so it can run the migration for the release. In a real release scenario you would most likely use the latest build from your main or production branch.
Drag a run job node and select the migrate db job from the dropdown. Toggle wait for completion on, so the next node won't run until the job finishes the migration successfully and save node.
Finally add another deploy build node, selecting the same build service and build as before, but this time with Rails deployment as the target, and save node. This will deploy the latest build of the new application feature branch.
Now save release flow and exit the editor.
Click run on the release flow for the production stage of your pipeline. Click add release name and name the release Add author field. You can also add a description to releases if you need to include more information.
You will see the job and deployment service listed in the run dialog where you can override the builds to deploy for each. Ignore this for now, and click run.
The release flow will now begin running, and the view of the run will automatically open. Each node should move from waiting to completed in sequence. When it has completed, visit the Northflank-generated URL for your deployment to check the Rails application. Click New Article to see it has added the Author field. Fill out and submit the form to check the field has been added to the database and the app can submit and retrieve the data.
Return to the pipeline on Northflank and click the options button (three vertical dots) next to your production release flow to see the menu. Select view release flow runs to see a list of past runs. You should see your run Add author field in the list, with information about the run.
Click on the run to see the result again, and note the buttons in the top-right of the run view: roll back to this release and view rollbacks. Rolling back allows you to quickly revert to a previous deployment if you need to.
This project template and release flow example is only one way of configuring a simple build, deploy, and release workflow on Northflank. You can adapt the tools and principles demonstrated here to suit your own needs, and automate complex tasks to run with a single click, push to a repository, or API/CLI command.
