> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shardcloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Host Ruby on Rails Applications

> Learn how to deploy Ruby on Rails applications on Shard Cloud.

## Introduction

This guide covers deploying Ruby on Rails applications on Shard Cloud. Rails is a full-stack web framework for Ruby that emphasizes convention over configuration and rapid development.

## Creating Your Project

Ensure you have **Ruby** and **Rails** installed.

### Creating a New Rails Project

```bash theme={null}
rails new my_rails_app
cd my_rails_app
```

### Basic Application Structure

Your Rails application should have this structure:

```
my_rails_app/
├── app/
│   ├── controllers/
│   ├── models/
│   └── views/
├── bin/
├── config/
├── db/
├── lib/
├── public/
├── Gemfile
└── .shardcloud
```

### Configuring Port 80

Update `config/puma.rb` to use port 80:

```ruby config/puma.rb theme={null}
port ENV.fetch("PORT") { 80 }
```

Or bind to all interfaces:

```ruby config/puma.rb theme={null}
bind "tcp://0.0.0.0:#{ENV.fetch('PORT') { 80 }}"
```

## Shard Cloud Configuration

Create a `.shardcloud` file:

```systemd .shardcloud theme={null}
DISPLAY_NAME=Rails Website
DESCRIPTION=Ruby on Rails Application
MAIN=Gemfile
MEMORY=512
VERSION=recommended
SUBDOMAIN=my-rails-site
CUSTOM_COMMAND=chmod +x bin/rails && bin/rails server -b 0.0.0.0
```

<Note>
  The `CUSTOM_COMMAND` makes the Rails binary executable and starts the server bound to all interfaces.
</Note>

## Deploying

<Steps>
  <Step title="Verify Locally">
    Run `bin/rails server` to verify your application works locally.
  </Step>

  <Step title="Prepare Your Files">
    Ensure you have:

    * All source files (`app/`, `config/`, `db/`, `lib/`, `public/`)
    * `bin/` folder (contains Rails executables)
    * `Gemfile`
    * `.shardcloud`
  </Step>

  <Step title="Exclude Unnecessary Files">
    Remove:

    * `vendor/bundle/`
    * `.bundle/`
    * `tmp/`
    * `log/`
    * `node_modules/` (if present)
  </Step>

  <Step title="Create ZIP Archive">
    Zip the entire Rails application folder.
  </Step>

  <Step title="Upload to Shard Cloud">
    Go to [Shard Cloud Dashboard](https://shardcloud.app/dash/applications) and upload.
  </Step>
</Steps>

## Database Configuration

If your Rails app uses a database, configure it in `config/database.yml`:

```yaml config/database.yml theme={null}
production:
  adapter: postgresql
  url: <%= ENV['DATABASE_URL'] %>
  pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
```

Set the `DATABASE_URL` environment variable in your Shard Cloud dashboard.

### Running Migrations

You can run migrations by updating your custom command:

```systemd .shardcloud theme={null}
CUSTOM_COMMAND=chmod +x bin/rails && bin/rails db:migrate && bin/rails server -b 0.0.0.0
```

## Additional Resources

Visit the [official Rails documentation](https://guides.rubyonrails.org/) for more information.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Permission denied for bin/rails">
    The `chmod +x bin/rails` in CUSTOM\_COMMAND should fix this. Make sure the `bin/` folder is included in your ZIP.
  </Accordion>

  <Accordion title="Dependencies not found">
    * Make sure `Gemfile` includes all required gems
    * Remove `vendor/bundle/` folder before uploading (Shard Cloud will install gems)
  </Accordion>

  <Accordion title="Assets not loading">
    * Precompile assets before uploading: `bin/rails assets:precompile`
    * Or add to CUSTOM\_COMMAND: `bin/rails assets:precompile && bin/rails server -b 0.0.0.0`
  </Accordion>

  <Accordion title="Database connection errors">
    * Verify `DATABASE_URL` environment variable is set in dashboard
    * Ensure `config/database.yml` reads from environment variables
  </Accordion>

  <Accordion title="Server not accessible">
    * Ensure `-b 0.0.0.0` is included to bind to all interfaces
    * Check that port 80 is configured in `config/puma.rb`
  </Accordion>
</AccordionGroup>