## Prerequisites
* Basic Ruby knowledge
* macOS (though Windows/Linux instructions available)
* [Upsun CLI](https://docs.upsun.com/administration/cli.html) installed
* [Ruby](https://www.ruby-lang.org/) 3.3+ installed
## Part 1: Local Development
### Setting Up Your Environment
First, let's install Ruby and Rails on your Mac:
```bash {filename="Terminal"} theme={null}
# Install Ruby 3.3 via brew
brew install ruby
# Install Rails 8 RC
gem install rails -v8.0.0.rc1
# Ensure bundler is up to date especially if you just upgraded Ruby
gem uninstall bundler --all --force && gem install bundler
```
If you want to use PostgreSQL locally via the `pg` gem, you need to install `postgresql@15` on your machine to compile the extension:
```bash {filename="Terminal"} theme={null}
brew install postgresql@15
gem install pg
```
If you only want to use `sqlite` locally and `pg` on your production install, you will need to add `bundle config set frozen false` to the Upsun build phase so that `bundle` can still install the gem on Upsun.
### Bootstraping your Rails 8 blog
Let's create a new Rails application:
```bash {filename="Terminal"} theme={null}
rails new rails-blog
cd rails-blog
```
Published on: <%= article.created_at.strftime("%B %d, %Y") %>
<% end %> <%= link_to "Read more", article_path(article), class: "inline-block mt-4 text-blue-600 hover:text-blue-800 hover:underline" %>No articles found.
<% end %><%= comment.commenter %>
<%= comment.body %>
**Great! Our app is now complete!**
## Part 2: Preparing for Upsun deployment
### Creating Your Upsun Project
```bash {filename="Terminal"} theme={null}
# Create a new project
upsun project:create rails-blog
# Follow the prompts!
[...]
```
Our Upsun git remote is now setup on the repository:
```shell {filename="Terminal"} theme={null}
git remote -v
origin git@github.com:gmoigneu/upsun-rails-8-tutorial.git (fetch)
origin git@github.com:gmoigneu/upsun-rails-8-tutorial.git (push)
upsun 6hd2pooi7mzay@git.ch-1.platform.sh:6hd2pooi7mzay.git (fetch)
upsun 6hd2pooi7mzay@git.ch-1.platform.sh:6hd2pooi7mzay.git (push)
```
### Configuring for Deployment
The magic happens in `.upsun/config.yaml`.
Let's break down each section of a production-ready Rails configuration:
#### 1. Application Definition
```yaml {filename=".upsun/config.yaml"} theme={null}
applications:
rails-blog:
type: "ruby:3.3"
```
This defines your application's runtime environment:
* `rails-blog` is your application name
* `type: "ruby:3.3"` specifies the base image we want to use and the Ruby version
#### 2. Database Relationship
```yaml {filename=".upsun/config.yaml"} theme={null}
relationships:
database: "postgresql:15"
```
This creates a connection between your application and services:
* Links your app to a PostgreSQL 15 database
* Makes the database credentials available via environment variables `DATABASE_`.
* Creates a secure internal network between your app and database
#### 3. Web Server Configuration
```yaml {filename=".upsun/config.yaml"} theme={null}
web:
commands:
start: "bundle exec puma -b unix://$SOCKET"
upstream:
socket_family: unix
locations:
"/":
root: "public"
passthru: true
expires: 1h
```
This configures how your application handles web requests:
* `start` command launches Puma using a Unix socket
* `socket_family: unix` optimizes for performance by using Unix sockets instead of TCP
* `locations` configures the web server:
* `root: "public"` serves static files from the public directory
* `passthru: true` forwards requests to Rails when no static file is found
* `expires: 1h` sets cache headers for better performance
#### 4. Build and Deploy Hooks
```yaml {filename=".upsun/config.yaml"} theme={null}
hooks:
build: |
set -e
bundle config set frozen false
bundle install
bundle exec rails assets:precompile
deploy: |
set -e
bundle exec rails db:migrate
```
These hooks run at specific points in the deployment process:
* `build` runs during the build phase when you are not connected to any other services:
* Installs Ruby dependencies
* Compiles assets
* `deploy` runs when deploying the new container on the host:
* Runs database migrations
* You could other actions like cache clearing and the likes
#### 5. Persistent Storage
```yaml {filename=".upsun/config.yaml"} theme={null}
mounts:
"/log":
source: storage
source_path: log
"/storage":
source: storage
source_path: storage
"/tmp":
source: storage
source_path: tmp
```
Configures persistent storage for your application:
* `/log` for application logs
* `/storage` for uploaded files and Active Storage
* `/tmp` for temporary files
* Each mount persists data across deployments and can be shared between containers
#### 6. Environment Variables
```yaml {filename=".upsun/config.yaml"} theme={null}
variables:
env:
PIDFILE: "tmp/server.pid"
RAILS_ENV: "production"
```
Sets environment variables for your application:
* `PIDFILE` specifies where Puma should store its process ID
* `RAILS_ENV` ensures Rails runs in production mode
#### 7. Services Definition
```yaml {filename=".upsun/config.yaml"} theme={null}
services:
database:
type: postgresql:15
```
Defines the services your application needs:
* Creates a PostgreSQL 15 database instance
* Automatically manages backups and updates
* Provides high-availability configuration
#### 8. Routing Configuration
```yaml {filename=".upsun/config.yaml"} theme={null}
routes:
"https://{default}/":
type: upstream
upstream: "rails-blog:http"
"https://www.{default}":
type: redirect
to: "https://{default}/"
```
Configures how requests reach your application:
* Sets up HTTPS automatically
* Routes requests to your Rails application
* Redirects www to non-www (or vice versa)
* `{default}` is replaced with your environment URL
The last step is to make sure we properly generate the `DATABASE_URL` environment variable. Upsun automatically detects any `.environment` file at the root of the repository.
```bash {filename=".environment"} theme={null}
# Set database environment variables
export DATABASE_URL="postgres://${DATABASE_USERNAME}:${DATABASE_PASSWORD}@${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_PATH}"
```
And that's all you need!