> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# How to host a Ruby on Rails application (Puma)

# How to Host Ruby on Rails Applications on Square Cloud

Ruby on Rails is a powerful and highly structured full-stack framework. To deploy it into production on Square Cloud with maximum efficiency, the secret lies in separating the asset compilation stage from the web server execution.

---

## 1. Compilation and Build Preparation

Before running your application in production, Rails needs to consolidate its dependencies and compile all frontend files (CSS, JavaScript, images, and fonts). This process optimizes loading times and ensures the server does not need to process raw files on the fly.

Run the following commands in your local environment to prepare the production build:

```bash
# 1. Configure bundler for deployment/production mode
bundle config set --local deployment 'true'
bundle config set --local without 'development test'

# 2. Install production Gems
bundle install

# 3. Precompile assets into the public/assets folder
RAILS_ENV=production bundle exec rails assets:precompile
```

The precompile command will generate minified files with unique hashes inside `public/assets`, ready to be served at high speeds.

---

## 2. Production Execution Command

With the build prepared and assets compiled, your initialization command on Square Cloud should focus exclusively on bringing up the production HTTP server (Puma) pointing to the mandatory port.

In your dashboard or configuration file, use the following start command:

```bash
bundle exec puma -C config/puma.rb -p 80
```

---

## 3. Preparing the Deployment Package (.zip)

To upload your application, create a `.zip` file containing the clean structure of your project.

*   **What to INCLUDE:** The `app/`, `config/`, `db/`, `lib/`, and `public/` folders (essential, as it contains your compiled assets), along with the `Gemfile`, `Gemfile.lock`, `Rakefile`, and `config.ru` files.
*   **What to EXCLUDE:** 
    *   `.bundle/` (Local configurations)
    *   `log/` and `tmp/` (Local log and cache files that will be recreated on the server)
    *   `node_modules/` (If you use Node tools for assets, the build has already generated the final output in the public folder)

---

## 4. Performance Tips and Troubleshooting

*   **Terminal Logs:** Make sure to add the environment variable `RAILS_LOG_TO_STDOUT=true` in the Square Cloud panel so you can monitor access and errors in real time via the dashboard.
*   **Asset Error (404):** If your app starts but the layout looks broken (missing CSS), ensure that the `RAILS_SERVE_STATIC_FILES=true` variable is configured in your panel, allowing Puma to serve the `public` folder directly if you are not using a CDN.
*   **Production Mode:** Never forget to set the `RAILS_ENV=production` variable in your Square Cloud environment to activate all the framework's native optimizations.
```