@spree/docs 0.1.0

package/dist/developer/deployment/emails.md

@@ -0,0 +1,77 @@
+---
+title: Sending out Emails
+sidebarTitle: Emails
+description: Learn how to send transactional emails from your Spree application.
+---
+
+Spree sends transactional emails such as order confirmation, password reset, shipping notifications, etc. You can use any SMTP provider — Resend, Postmark, Mailgun, SendGrid, Amazon SES, or your own SMTP server.
+
+## Configuration
+
+Set the following environment variables to enable email delivery:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_HOST` | — | SMTP server address (e.g., `smtp.sendgrid.net`, `smtp.resend.com`) |
+| `SMTP_PORT` | `587` | SMTP server port |
+| `SMTP_USERNAME` | — | SMTP auth username |
+| `SMTP_PASSWORD` | — | SMTP auth password |
+| `SMTP_FROM_ADDRESS` | — | Default "from" email address (e.g., `orders@mystore.com`) |
+| `RAILS_HOST` | `example.com` | Host used in email URLs |
+
+When `SMTP_HOST` is not set, emails are printed to the Rails log instead of being sent.
+
+### Provider Examples
+
+**SendGrid:**
+
+```bash
+    SMTP_HOST=smtp.sendgrid.net
+    SMTP_USERNAME=apikey
+    SMTP_PASSWORD=SG.your-sendgrid-api-key
+    SMTP_FROM_ADDRESS=orders@mystore.com
+    ```
+
+    > **WARNING:** Remember to verify the email address in SendGrid you intend to use for sending, otherwise emails will be rejected.
+>     [Read more about sender verification](https://www.twilio.com/docs/sendgrid/ui/sending-email/sender-verification).
+
+  **Resend:**
+
+```bash
+    SMTP_HOST=smtp.resend.com
+    SMTP_USERNAME=resend
+    SMTP_PASSWORD=re_your-resend-api-key
+    SMTP_FROM_ADDRESS=orders@mystore.com
+    ```
+
+  **Postmark:**
+
+```bash
+    SMTP_HOST=smtp.postmarkapp.com
+    SMTP_USERNAME=your-postmark-server-token
+    SMTP_PASSWORD=your-postmark-server-token
+    SMTP_FROM_ADDRESS=orders@mystore.com
+    ```
+
+  **Amazon SES:**
+
+```bash
+    SMTP_HOST=email-smtp.us-east-1.amazonaws.com
+    SMTP_USERNAME=your-ses-access-key-id
+    SMTP_PASSWORD=your-ses-secret-access-key
+    SMTP_FROM_ADDRESS=orders@mystore.com
+    ```
+
+
+## Local Development
+
+In local development, emails are printed to the Rails log by default. To preview emails with a web UI, run [Mailpit](https://mailpit.axllent.org):
+
+```bash
+docker run -d --name mailpit -p 8025:8025 -p 1025:1025 axllent/mailpit
+SMTP_HOST=localhost bin/dev
+```
+
+Open [http://localhost:8025](http://localhost:8025) to see all outgoing emails.
+
+> **TIP:** If you're using `docker compose up` for development, Mailpit is included automatically and all emails are caught at [http://localhost:8025](http://localhost:8025).

package/dist/developer/deployment/environment_variables.md

@@ -0,0 +1,111 @@
+---
+title: Environment Variables
+---
+
+Spree uses environment variables for all deployment configuration. No secrets or credentials are stored in the codebase.
+
+## Required
+
+These variables are required to run Spree in production.
+
+| Variable | Description | Example |
+| --- | --- | --- |
+| `DATABASE_URL` | PostgreSQL connection URL | `postgres://user:pass@localhost:5432/spree` |
+| `REDIS_URL` | Redis URL for background jobs (Sidekiq) and Action Cable | `redis://localhost:6379/0` |
+| `REDIS_CACHE_URL` | Redis URL for caching (optional — falls back to `REDIS_URL`) | `redis://localhost:6380/0` |
+| `SECRET_KEY_BASE` | Secret key for session encryption. Generate with `bin/rails secret` | `2fad5c0b79d25e4765d3018d8c740f8c3a665f0e5c...` |
+
+## Email (SMTP)
+
+Spree works with any SMTP provider (Resend, Postmark, Mailgun, SendGrid, Amazon SES, etc.). Set `SMTP_HOST` to enable email delivery — when not set, emails are logged to stdout.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_HOST` | — | SMTP server address (e.g., `smtp.sendgrid.net`) |
+| `SMTP_PORT` | `587` | SMTP server port |
+| `SMTP_USERNAME` | — | SMTP auth username |
+| `SMTP_PASSWORD` | — | SMTP auth password |
+| `SMTP_FROM_ADDRESS` | — | Default "from" email address |
+| `RAILS_HOST` | `example.com` | Host used in email URLs |
+
+## Web Server
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PORT` | `3000` | Web server port |
+| `RAILS_MAX_THREADS` | `3` | Puma threads per worker |
+| `WEB_CONCURRENCY` | `1` | Number of Puma workers. Set to `auto` for one per CPU core |
+
+## Application
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `RAILS_ENV` | `production` | Rails environment |
+| `RAILS_LOG_LEVEL` | `info` | Log level (`debug`, `info`, `warn`, `error`) |
+
+## File Storage (S3 / Cloudflare R2)
+
+By default, uploaded files (product images, assets) are stored on the local filesystem. Set the appropriate credentials to use cloud storage instead. Spree auto-detects the provider based on which credentials are present.
+
+### Amazon S3
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `AWS_ACCESS_KEY_ID` | — | AWS access key |
+| `AWS_SECRET_ACCESS_KEY` | — | AWS secret key |
+| `AWS_REGION` | — | AWS region (e.g., `us-east-1`) |
+| `AWS_BUCKET` | `spree-production` | S3 bucket name |
+
+### Cloudflare R2
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `CLOUDFLARE_ENDPOINT` | — | R2 endpoint URL |
+| `CLOUDFLARE_ACCESS_KEY_ID` | — | R2 access key |
+| `CLOUDFLARE_SECRET_ACCESS_KEY` | — | R2 secret key |
+| `CLOUDFLARE_BUCKET` | `spree-production` | R2 bucket name |
+
+## Search (Meilisearch)
+
+Optional. When configured, Spree uses [Meilisearch](/integrations/search/meilisearch) for product search, filtering, and faceted navigation instead of SQL.
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `MEILISEARCH_URL` | `http://localhost:7700` | Meilisearch server URL |
+| `MEILISEARCH_API_KEY` | — | Meilisearch master key. Not needed for local development — only required when Meilisearch is started with `MEILI_MASTER_KEY`. |
+
+After setting these, enable the provider and reindex:
+
+```ruby
+# config/initializers/spree.rb
+Spree.search_provider = 'Spree::SearchProvider::Meilisearch'
+```
+
+```bash
+rake spree:search:reindex
+```
+
+## Error Tracking (Sentry)
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SENTRY_DSN` | — | [Sentry](https://sentry.io/) DSN. When set, errors are reported to Sentry |
+
+## SSL
+
+By default, Spree assumes it runs behind an SSL-terminating reverse proxy. Set these to `false` if running without SSL (e.g., local development or behind a proxy that doesn't do SSL termination).
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `RAILS_ASSUME_SSL` | `true` | Assume requests arrive via SSL (sets `X-Forwarded-Proto`) |
+| `RAILS_FORCE_SSL` | `true` | Redirect HTTP to HTTPS and use secure cookies |
+
+## Local Development
+
+These variables are used when running the `server/` app locally (not via `DATABASE_URL`):
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `DATABASE_HOST` | `localhost` | PostgreSQL host |
+| `DATABASE_PORT` | `5432` | PostgreSQL port |
+| `DATABASE_USERNAME` | `postgres` | PostgreSQL user |

package/dist/developer/deployment/heroku.md

@@ -0,0 +1,51 @@
+---
+title: Heroku
+section: deployment
+---
+
+# Heroku
+
+## Overview
+
+Heroku is a Platform as a Service that makes deploying and hosting Spree applications super easy.
+
+You should just follow [Heroku Rails 6 guide](https://devcenter.heroku.com/articles/getting-started-with-rails6).
+
+We recommend you start and stick to Heroku if you do not have DevOps-skilled team members. [Spree Starter](https://github.com/spree/spree_starter) is pre-configured to work with Heroku out of the box.
+
+## Dynos
+
+[Heroku Dynos](https://www.heroku.com/dynos) are lightweight, isolated environments that provide compute and run your application.
+
+There are 2 types of dynos:
+
+* **Web** - for running the web interface of yuour Store Storefront, API, Admin Panel
+* **Worker** - for running background jobs via [Active Job](https://guides.rubyonrails.org/active_job_basics.html) such as email send out, report generation, etc
+
+### Recommended sizing
+
+| Dynos | Staging environment | Production environment |
+| :--- | :--- | :--- |
+| **web** | 1 x Standard-2x | 1 x Performance-M or Performance-L |
+| **worker** | 1 x Standard-1x | 1 x Standard-1x |
+
+## Add-Ons
+
+[Heroku Add-Ons](https://elements.heroku.com/addons) are tools and services for developing, extending, and operating your app.
+
+### Recommended Add-Ons and plans
+
+| Plan | Staging environment | Production environment |
+| :--- | :--- | :--- |
+| Bucketeer | Hobbyist | Micro |
+| Edge | Hobby | Micro |
+| Heroku Postgres | Hobby Basic | Standard-0 |
+| Sendgrid | Free | Bronze |
+| Sentry | Free | Small |
+
+## Other resources
+
+* [https://devcenter.heroku.com/categories/reference](https://devcenter.heroku.com/categories/reference)
+* [https://devcenter.heroku.com/articles/getting-started-with-rails6](https://devcenter.heroku.com/articles/getting-started-with-rails6)
+* [https://devcenter.heroku.com/categories/monitoring-metrics](https://devcenter.heroku.com/categories/monitoring-metrics)
+* [https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server](https://devcenter.heroku.com/articles/deploying-rails-applications-with-the-puma-web-server)

package/dist/developer/deployment/render.md

@@ -0,0 +1,95 @@
+---
+title: Render
+description: Deploy Spree to Render with one click.
+---
+
+## One-Click Deploy
+
+The fastest way to get Spree running on Render:
+
+[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/spree/spree-starter)
+
+This creates all required services automatically:
+
+- **Web** — Rails app serving the API and admin panel
+- **Worker** — Sidekiq for background jobs
+- **PostgreSQL** — database
+- **Redis** — caching, jobs, Action Cable
+
+The database is seeded on first deploy. Your store is ready in a few minutes.
+
+## Prerequisites
+
+- [Render account](https://render.com) with a credit card on file
+- [GitHub account](https://github.com)
+
+## Custom Deployment
+
+If you need to customize the backend (add gems, models, etc.), start from the [Spree Starter](https://github.com/spree/spree-starter) template:
+
+1. Go to [spree/spree-starter](https://github.com/spree/spree-starter) and click **Use this template** > **Create a new repository**
+
+2. Clone your new repository and make your changes
+
+3. In the Render dashboard, click **New** > **Blueprint** and select your repository
+
+4. Render reads the `render.yaml` from your repo and creates all services. Review and click **Deploy Blueprint**.
+
+The included [`render.yaml`](https://github.com/spree/spree-starter/blob/main/render.yaml) handles:
+- Build: `bundle install`, asset precompilation, `db:prepare`, `db:seed`
+- Web: Puma with health check on `/up`
+- Worker: Sidekiq with shared `SECRET_KEY_BASE`
+- PostgreSQL 18 and Redis
+
+## After Deployment
+
+### Admin Dashboard
+
+Access your admin panel at:
+
+```
+https://<your-app-name>.onrender.com/admin
+```
+
+Default credentials are created during `db:seed`. Change them immediately after first login.
+
+### Environment Variables
+
+Render sets `DATABASE_URL`, `REDIS_URL`, and `SECRET_KEY_BASE` automatically from the blueprint. For additional configuration (SMTP, file storage, Sentry, etc.), see [Environment Variables](/developer/deployment/environment_variables).
+
+## Production Sizing
+
+The free/starter plans work for trying Spree. For production workloads, we recommend:
+
+| Service | Plan | Resources | Auto-scaling |
+|---|---|---|---|
+| **Web** | Pro | 4 GB RAM, 2 CPU | 2–3 instances |
+| **Worker** | Standard | 2 GB RAM, 1 CPU | — |
+| **PostgreSQL** | Pro 4 GB | 4 GB RAM, 1 CPU | — |
+| **Redis** (jobs) | Standard | 1 GB RAM | — |
+| **Redis** (cache) | Standard | 1 GB RAM | — |
+
+To enable auto-scaling, add this to the web service in your `render.yaml`:
+
+```yaml
+- type: web
+  name: spree
+  plan: pro
+  scaling:
+    minInstances: 2
+    maxInstances: 3
+    targetMemoryPercent: 80
+    targetCPUPercent: 80
+```
+
+## Next Steps
+
+Render provides ephemeral storage — uploaded files (product images, etc.) won't persist across deploys. Set up cloud storage:
+
+- [Asset Storage](/developer/deployment/assets) (Amazon S3 / Cloudflare R2)
+
+Before going to production:
+
+- [Set environment variables](/developer/deployment/environment_variables) (SMTP, SSL, etc.)
+- [Configure CDN](/developer/deployment/cdn)
+- [Configure caching](/developer/deployment/caching)

package/dist/developer/getting-started/quickstart.md

@@ -0,0 +1,82 @@
+---
+title: "Installing Spree"
+sidebarTitle: Installation
+description: "Follow the instructions below to learn how to build and deploy your Spree application."
+---
+
+## Installation options
+
+**create-spree-app:**
+
+The quickest way to get started. Scaffolds a full Spree project with Next.js Storefront (optional).
+
+    **Requirements:** [Node.js](https://nodejs.org/) 20+ and [Docker](https://docs.docker.com/get-docker/) running.
+
+    ```bash
+    npx create-spree-app@latest my-store
+    ```
+
+    The CLI walks you through an interactive setup:
+
+    1. Choose **Full-stack** (Backend + Next.js Storefront) or **Backend only**
+    2. Optionally load **sample data** (products, categories, images)
+
+    Once complete, your store should be running at [http://localhost:3000/admin](http://localhost:3000/admin). The port can be different if `3000` is already used on your system.
+
+    See the full [create-spree-app documentation](/developer/create-spree-app/quickstart) for all CLI flags and options.
+
+  **Manual Installation:**
+
+For developers who prefer full control over the setup, or want to add Spree to an existing Rails application.
+
+    1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/)
+    2. Install [vips](https://www.libvips.org/install.html) for image processing
+    3. Install Rails gem:
+        ```bash
+        gem install rails
+        ```
+    4. Create a new Spree application:
+        ```bash
+        rails new my_store -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
+        ```
+        To use a specific database, pass the `-d` flag:
+        ```bash
+        rails new my_store -d postgresql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
+        rails new my_store -d mysql -m https://raw.githubusercontent.com/spree/spree/main/spree/template.rb
+        ```
+    5. Navigate to the application directory:
+        ```bash
+        cd my_store
+        ```
+    6. Start the development server:
+        ```bash
+        bin/dev
+        ```
+    7. Optionally load sample data (products, categories, etc.):
+        ```bash
+        bin/rails spree_sample:load
+        ```
+
+    > **INFO:** Spree works with **PostgreSQL**, **MySQL**, and **SQLite** databases. The Rails template defaults to SQLite for quick setup. You can switch to PostgreSQL or MySQL at any time. [Learn more about database configuration](/developer/deployment/database).
+
+
+## Accessing Admin Panel
+
+Navigate to [http://localhost:3000/admin](http://localhost:3000/admin) and log in with the default credentials:
+
+| | |
+|---|---|
+| **Email** | `spree@example.com` |
+| **Password** | `spree123` |
+
+Upon successful authentication, you should see the admin screen:
+
+<img src="/images/spree_admin_dashboard.png" />
+
+---
+
+Congrats! You've set up your Spree Commerce and it's looking amazing!
+
+Give Spree a [GitHub Star](https://github.com/spree/spree), why dont't ya? Thank you for supporting Spree open-source! 
+
+Need support or want to give some feedback? Join our [community](https://slack.spreecommerce.org/) with 6000+ members or drop us an email at [hello@spreecommerce.org](mailto:hello@spreecommerce.org).