Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Update README.md

Damian Legawieca3a486f4ba4e
diff --git a/backend/README.md b/backend/README.md
index 7db80e4ca1..5bdbd6a947 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -1,24 +1,100 @@
-# README
+# Spree Backend
-This README would normally document whatever steps are necessary to get the
-application up and running.
+A Rails application that serves as the Spree Commerce backend. It mounts the Spree engines (core, api, admin, emails, sample) from the `engines/` directory and provides the API and admin interface.
-Things you may want to cover:
+## Structure
-* Ruby version
+```
+backend/
+├── Gemfile # References engines via path
+├── Dockerfile # Multi-stage build for Docker
+├── config/
+├── db/
+└── engines/
+ ├── core/ # spree_core - models, services, business logic
+ ├── api/ # spree_api - Storefront & Platform REST APIs
+ ├── admin/ # spree_admin - admin dashboard
+ ├── emails/ # spree_emails - transactional emails
+ └── sample/ # spree_sample - sample seed data
+```
-* System dependencies
+## Setup
-* Configuration
+### Prerequisites
-* Database creation
+- Ruby 4.0+
+- PostgreSQL 16+
+- libvips (for image processing)
-* Database initialization
+### Local Development (Ruby developers)
-* How to run the test suite
+```bash
+cd backend
+bundle install
+bin/rails db:prepare
+bin/rails server
+```
-* Services (job queues, cache servers, search engines, etc.)
+The app starts at `http://localhost:3000`.
-* Deployment instructions
+### Docker (TypeScript / frontend developers)
-* ...
+From the **repository root**:
+
+```bash
+docker compose up -d
+```
+
+This boots PostgreSQL and the backend. The API is available at `http://localhost:3000`. The database is automatically created and migrated on first boot.
+
+To rebuild after changes:
+
+```bash
+docker compose build backend
+docker compose up -d
+```
+
+To reset the database:
+
+```bash
+docker compose down -v
+docker compose up -d
+```
+
+## Environment Variables
+
+### Database
+
+| Variable | Default | Description |
+|---|---|---|
+| `DATABASE_HOST` | `localhost` | PostgreSQL host |
+| `DATABASE_PORT` | `5432` | PostgreSQL port |
+| `DATABASE_USERNAME` | `postgres` | PostgreSQL user |
+
+### Production
+
+| Variable | Required | Description |
+|---|---|---|
+| `DATABASE_URL` | Yes | Primary database connection URL |
+| `CACHE_DATABASE_URL` | No | Solid Cache database (falls back to `DATABASE_URL`) |
+| `QUEUE_DATABASE_URL` | No | Solid Queue database (falls back to `DATABASE_URL`) |
+| `CABLE_DATABASE_URL` | No | Action Cable database (falls back to `DATABASE_URL`) |
+| `SECRET_KEY_BASE` | Yes | Secret key for session encryption |
+
+## Running Engine Tests
+
+Each engine has its own test suite. You must first install the engines root bundle, then the engine-specific one:
+
+```bash
+# Install shared dependencies (required once)
+cd backend/engines
+bundle install
+
+# Run tests for a specific engine
+cd core
+bundle install
+bundle exec rake test_app # generates a dummy Rails app for testing
+bundle exec rspec spec
+```
+
+Replace `core` with `api`, `admin`, `emails`, or `sample` to test other engines.