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.

Updated tutorials and added Add Spree to an existing app tutorial (#10691)

Damian Legawiec33287208dc67
diff --git a/README.md b/README.md
index b5f1179213..b22bea9636 100755
--- a/README.md
+++ b/README.md
@@ -54,87 +54,11 @@ Admin panel credentials for your own Heroku demo:
1. [Install Docker](https://docs.docker.com/get-docker/)
2. Download [Spree Starter](https://github.com/spree/spree_starter/archive/main.zip)
3. Unzip it
-4. Run `bin/setup` in `spree_starter` directory
+4. Run `bin/setup` in `spree_starter-main` directory
### Option B - add Spree to an existing application
-1. Add Spree gems to your `Gemfile`
-
- ##### Rails 6.0 and 6.1
-
- ```ruby
- gem 'spree', '~> 4.2.0.rc3'
- gem 'spree_auth_devise', '~> 4.3'
- gem 'spree_gateway', '~> 3.9'
- ```
-
- ##### Rails 5.2
-
- ```ruby
- gem 'spree', '~> 3.7.0'
- gem 'spree_auth_devise', '~> 3.5'
- gem 'spree_gateway', '~> 3.4'
- ```
-
- To see what rails version are you using run this command:
-
- ```bash
- rails -v
- ```
-
- Older rails versions are also supported: [Rails 5.1](https://guides.spreecommerce.org/release_notes/3_5_0.html), [Rails 5.0](https://guides.spreecommerce.org/release_notes/3_2_0.html), [Rails 4.2](https://guides.spreecommerce.org/release_notes/3_1_0.html)
-
-2. Install gems
-
- ```bash
- bundle install
- ```
-
- **Note**: if you run into `Bundler could not find compatible versions for gem "sprockets":` error message, please run
-
- ```bash
- bundle update
- ```
-
-3. Use the install generators to set up Spree
-
- ```shell
- bundle exec rails g spree:install --user_class=Spree::User
- bundle exec rails g spree:auth:install
- bundle exec rails g spree_gateway:install
- ```
-
-#### Installation options
-
-By default, the installation generator (`rails g spree:install`) will run
-migrations as well as adding seed and sample data and will copy storefront data
-for easy customization (if `spree_frontend` available). This can be disabled using
-
-```shell
-rails g spree:install --migrate=false --sample=false --seed=false --copy_storefront=false
-```
-
-You can always perform any of these steps later by using these commands.
-
-```shell
-bundle exec rake railties:install:migrations
-bundle exec rails db:migrate
-bundle exec rails db:seed
-bundle exec rake spree_sample:load
-bundle exec rails g spree:frontend:copy_storefront
-```
-
-#### Headless installation
-
-To use Spree in [API-only mode](https://guides.spreecommerce.org/api/overview/) you need to replace `spree` with `spree_api` in your project Gemfile. This will skip Storefront and Admin Panel. If you would want to include the Admin Panel please add `spree_backend` to your Gemfile.
-
-## Browse Storefront
-
-Go to http://localhost:3000
-
-## Browse Admin Panel
-
-Go to http://localhost:3000/admin
+1. [Please follow Add Spree to an existing Ruby on Rails application tutorial](https://guides.spreecommerce.org/developer/tutorials/getting_started_tutorial.html)
## Extensions
diff --git a/guides/src/content/developer/tutorials/deface_overrides_tutorial.md b/guides/src/content/developer/tutorials/deface_overrides_tutorial.md
index 673d245aca..27f6357f02 100644
--- a/guides/src/content/developer/tutorials/deface_overrides_tutorial.md
+++ b/guides/src/content/developer/tutorials/deface_overrides_tutorial.md
@@ -1,7 +1,6 @@
---
title: Deface Overrides
section: tutorial
-hidden: true
---
<alert kind="warning">
diff --git a/guides/src/content/developer/tutorials/developing_spree.md b/guides/src/content/developer/tutorials/developing_spree.md
index 331fdcdf95..c22caf50bf 100644
--- a/guides/src/content/developer/tutorials/developing_spree.md
+++ b/guides/src/content/developer/tutorials/developing_spree.md
@@ -1,6 +1,7 @@
---
title: Developing Spree
section: tutorial
+order: 2
---
## Overview
@@ -29,7 +30,7 @@ If `bundle install` fails that means you're missing some required system librari
Firstly, please [install homebew](https://brew.sh/). With homebrew installed you will need to install some packages needed to run Spree and Rails applications in general:
```bash
-brew install openssl mysql postgresql sqlite
+brew install openssl mysql postgresql sqlite imagemagick
```
## Sandbox
diff --git a/guides/src/content/developer/tutorials/existing_app_tutorial.md b/guides/src/content/developer/tutorials/existing_app_tutorial.md
new file mode 100644
index 0000000000..b31aaf6dcf
--- /dev/null
+++ b/guides/src/content/developer/tutorials/existing_app_tutorial.md
@@ -0,0 +1,149 @@
+---
+title: Add Spree to an existing Ruby on Rails application
+section: tutorial
+order: 1
+---
+
+## Prerequisites
+
+Before starting this tutorial, please check which Rails version are you using by running:
+
+```bash
+bundle exec rails -v
+```
+
+in your project root directory.
+
+## Installation
+
+1. Add Spree gems to your `Gemfile`
+
+ **Rails 6.0 and 6.1**
+
+ ```ruby
+ gem 'spree', '~> 4.2.0.rc3'
+ gem 'spree_auth_devise', '~> 4.3'
+ gem 'spree_gateway', '~> 3.9'
+ ```
+
+ **Rails 5.2**
+
+ ```ruby
+ gem 'spree', '~> 3.7.0'
+ gem 'spree_auth_devise', '~> 3.5'
+ gem 'spree_gateway', '~> 3.4'
+ ```
+
+ **Rails 5.1**
+
+ ```ruby
+ gem 'spree', '~> 3.5.0'
+ gem 'spree_auth_devise', '~> 3.3'
+ gem 'spree_gateway', '~> 3.3'
+ ```
+
+ **Rails 5.0**
+
+ ```ruby
+ gem 'spree', '~> 3.2.0'
+ gem 'spree_auth_devise', '~> 3.2.0'
+ gem 'spree_gateway', '~> 3.2.0'
+ ```
+
+2. Install gems
+
+ ```bash
+ bundle install
+ ```
+
+ **Note**: if you run into `Bundler could not find compatible versions for gem "sprockets":` error message, please run
+
+ ```bash
+ bundle update
+ ```
+
+3. Use the install generators to set up Spree
+
+ ```shell
+ bundle exec rails g spree:install --user_class=Spree::User
+ bundle exec rails g spree:auth:install
+ bundle exec rails g spree_gateway:install
+ ```
+
+### Installation options
+
+By default, the installation generator (`rails g spree:install`) will run
+migrations as well as adding seed and sample data and will copy storefront data
+for easy customization (if `spree_frontend` available). This can be disabled using
+
+```shell
+rails g spree:install --migrate=false --sample=false --seed=false --copy_storefront=false
+```
+
+You can always perform any of these steps later by using these commands.
+
+```shell
+bundle exec rake railties:install:migrations
+bundle exec rails db:migrate
+bundle exec rails db:seed
+bundle exec rake spree_sample:load
+bundle exec rails g spree:frontend:copy_storefront
+```
+
+### Headless installation (API-mode)
+
+To use Spree in [API-only mode](https://guides.spreecommerce.org/api/overview/) you need to replace `spree` with `spree_api` in your project Gemfile. This will skip Storefront and Admin Panel. If you would want to include the Admin Panel please add `spree_backend` to your Gemfile.
+
+### Mounting the Spree engine
+
+When `rails g spree:install` is run inside an application, it will install Spree, mounting the `Spree::Core::Engine` component by inserting this line automatically
+into `config/routes.rb`:
+
+```ruby
+mount Spree::Core::Engine, at: '/'
+```
+
+By default, all Spree routes will be available at the root of your domain. For example, if your domain is `http://localhost:3000`, Spree’s `/products` URL will be available at `http://localhost:3000/products`.
+
+You can customize this simply by changing the `:at` specification in `config/routes.rb` to be something else. For example, if you would like Spree to be mounted at `/shop`, you can write this:
+
+```ruby
+mount Spree::Core::Engine, at: `/shop`
+```
+
+The different parts of Spree (API, Admin) will be mounted there as well, eg. `http://localhost:3000/shop/admin`.
+
+### Use your existing authentication
+
+[Spree Auth Devise](https://github.com/spree/spree_auth_devise) is the default authnetication that comes with Spree but you can swap it for your own, please [follow this guide](/developer/customization/authentication.html)
+
+## Hello, Spree Commerce
+
+You now have a functional Spree application after running only a few commands!
+
+To see your application in action, open a browser window and navigate to [http://localhost:3000](http://localhost:3000). You should see the Spree default home page:
+
+![Spree Application Home Page](../../../images/developer/storefront/1.png)
+
+To stop the web server, hit Ctrl-C in the terminal window where it's running. In development mode, Spree does not generally require you to stop the server; changes you make in files will be automatically picked up by the server.
+
+### Logging Into the Admin Panel
+
+The next thing you'll probably want to do is to log into the admin interface.
+Use your browser window to navigate to
+[http://localhost:3000/admin](http://localhost:3000/admin). You can login with
+the username `[email protected]` and password `spree123`.
+
+Upon successful authentication, you should see the admin screen:
+
+![Admin Screen](../../../images/developer/overview.png)
+
+Feel free to explore some of the Admin Panel features that Spree has to offer and to verify that your installation is working properly.
+
+## Next steps
+
+If you've followed the steps described in this tutorial, you should now have a fully functional Spree application up and running.
+
+We recommend you should continue to [Customization section](/developer/customization/storefront.html) to learn how to modify and extend your Spree application.
+
+To learn more about Spree internals please refer [Core section](/developer/core/orders.html).
diff --git a/guides/src/content/developer/tutorials/extend_product_attributes.md b/guides/src/content/developer/tutorials/extend_product_attributes.md
index ea17006e7f..9547701aa6 100644
--- a/guides/src/content/developer/tutorials/extend_product_attributes.md
+++ b/guides/src/content/developer/tutorials/extend_product_attributes.md
@@ -1,7 +1,6 @@
---
title: 'Extend Product Attributes'
section: tutorial
-order: 0
---
## Overview
diff --git a/guides/src/content/developer/tutorials/extensions_tutorial.md b/guides/src/content/developer/tutorials/extensions_tutorial.md
index 41f464f394..64ec53c4ad 100644
--- a/guides/src/content/developer/tutorials/extensions_tutorial.md
+++ b/guides/src/content/developer/tutorials/extensions_tutorial.md
@@ -7,6 +7,12 @@ section: tutorial
Let's build a simple [extension](/developer/customization/extensions.html). Suppose we want the ability to mark certain products as being on sale. We'd like to be able to set a sale price on a product and show products that are on sale on a separate products page. This is a great example of how an extension can be used to build on the solid Spree foundation.
+Before we start, let's make sure we have spree command installed by running:
+
+```ruby
+gem install spree
+```
+
So let's start by generating the extension. Run the following command from a directory of your choice outside of our Spree application:
```bash
diff --git a/guides/src/content/developer/tutorials/getting_started_tutorial.md b/guides/src/content/developer/tutorials/getting_started_tutorial.md
index 6ba120e760..533b1029f5 100644
--- a/guides/src/content/developer/tutorials/getting_started_tutorial.md
+++ b/guides/src/content/developer/tutorials/getting_started_tutorial.md
@@ -8,13 +8,16 @@ order: 0
Before starting this tutorial, make sure you have [Docker](https://docs.docker.com/get-docker/) installed on your system. This is fairly straightforward, but differs depending on which operating system you use.
+If you would like to add Spree to your existing Ruby on Rails application, please [follow this guide instead](/developer/tutorials/existing_app_tutorial.html).
+
## Installation
-1. Download [Spree Starter](https://github.com/spree/spree_starter/archive/master.zip)
+1. Download [Spree Starter](https://github.com/spree/spree_starter/archive/main.zip)
2. Unzip it
-3. Run `bin/setup` in `spree_starter` directory
+3. Rename `spree_starter-main` directory as you please
+4. Run `bin/setup` in said directory
-## Hello, Spree!
+## Hello, Spree Commerce
You now have a functional Spree application after running only a few commands!
@@ -37,10 +40,12 @@ Upon successful authentication, you should see the admin screen:
Feel free to explore some of the Admin Panel features that Spree has to offer and to verify that your installation is working properly.
-## Wrapping Up
+## Next steps
If you've followed the steps described in this tutorial, you should now have a fully functional Spree application up and running.
-We recommend you should continue to [Customization section](/developer/customization/storefront.html) to learn how to modify and extend your Spree application.
+For starting/stopping/restarting application please refer to [Spree Starter README](https://github.com/spree/spree_starter#running-the-project).
+
+We recommend you should also continue to [Customization section](/developer/customization/storefront.html) to learn how to modify and extend your Spree application.
To learn more about Spree internals please refer [Core section](/developer/core/orders.html).
diff --git a/guides/src/content/developer/tutorials/migration.md b/guides/src/content/developer/tutorials/migration.md
index d7c0307fd8..90df8a35ad 100644
--- a/guides/src/content/developer/tutorials/migration.md
+++ b/guides/src/content/developer/tutorials/migration.md
@@ -1,6 +1,7 @@
---
title: Migrating to Spree
section: advanced
+hidden: true
---
## Overview
diff --git a/guides/src/content/developer/tutorials/seo.md b/guides/src/content/developer/tutorials/seo.md
index 0d97ef3f20..42dbcf320d 100644
--- a/guides/src/content/developer/tutorials/seo.md
+++ b/guides/src/content/developer/tutorials/seo.md
@@ -1,7 +1,7 @@
---
title: 'Improve SEO'
section: advanced
-order: 0
+order: 3
---
## Overview
diff --git a/guides/src/content/developer/tutorials/testing.md b/guides/src/content/developer/tutorials/testing.md
index 2555ae66d8..48d63e8e57 100644
--- a/guides/src/content/developer/tutorials/testing.md
+++ b/guides/src/content/developer/tutorials/testing.md
@@ -90,55 +90,3 @@ end
```
This lets your Spree app behave as if this user is logged in.
-
-
-#### Testing as Someone Not Logged In
-
-For Spree 2.2 and prior, Spree keeps track of the order for a logged out user using a session variable. Here's an example that may work for you in Spree 2.2 and earlier:
-
-```ruby
-let (:order) { FactoryBot.create(:order) }
-before(:each) do
- page.set_rack_session(order_id: order.id)
- page.set_rack_session(access_token: order.token)
-end
-```
-
-In Spree 2.3, a signed cookie is used to keep track of the guest user's cart. In the example below, we make two stubs onto objects in Spree to fake-out the guest token (in this text example, we simply set it to 'xyz'). In the example, presume that the order factory will have a lineitem in it for an associated product called "Some Product":
-
-```ruby
-describe "cart to registration page", type: :feature do
- let(:order) { FactoryBot.create(:order, guest_token: "xyz") }
- # user should be nil for logged out user
-
-
- describe "as someone not logged in" do
- before(:each) do
- order
- SecureRandom.stub!(:urlsafe_base64)
- .with(any_args)
- .and_return("xyz")
-
- Spree::OrdersController.any_instance
- .stub(:cookies)
- .and_return(mock(:cookies, signed: {guest_token: "xyz"}))
- end
-
- it "should let me load the shopping cart page" do
- visit '/cart'
- page.status_code.should eq(200)
- expect(page).to have_content 'Some Product'
- end
-end
-```
-
-$$$
-TODO: We still are looking for a way to set a signed cookie on a RackTest driver. If you get that working, you can remove the stub on the Spree::OrdersController in the code example above.
-
-Thomas Walpole thinks code like this might work, but we have yet to get this working correctly:
-
-```ruby
-kg = ActiveSupport::KeyGenerator.new(Rails.application.secrets.secret_key_base, iterations:1000)
-guest_token_cookie_value_to_set = ActiveSupport::MessageVerifier.new(kg.generate_key("signed cookie"), digest: 'SHA1', serializer: ActiveSupport::MessageEncryptor::NullSerializer).generate("\"#{guest_token}\"")
-```
-$$$
diff --git a/guides/src/content/developer/tutorials/upgrading_extensions.md b/guides/src/content/developer/tutorials/upgrading_extensions.md
index 9e622d55f9..a569d6cf11 100644
--- a/guides/src/content/developer/tutorials/upgrading_extensions.md
+++ b/guides/src/content/developer/tutorials/upgrading_extensions.md
@@ -1,5 +1,5 @@
---
-title: Updating Extensions to Rails 6 and Spree 4.1
+title: Updating Extensions to Rails 6 and Spree 4
section: advanced
---
diff --git a/guides/src/content/release_notes/4_2_0.md b/guides/src/content/release_notes/4_2_0.md
index bd1b3c0404..27db5ffb2e 100644
--- a/guides/src/content/release_notes/4_2_0.md
+++ b/guides/src/content/release_notes/4_2_0.md
@@ -77,29 +77,10 @@ We've invested a lot of time to make the default Storefront accessible for every
## Installation
-### Add Spree gems to Gemfile
-
-```ruby
-gem 'spree', '~> 4.2.0.rc3'
-gem 'spree_auth_devise', '~> 4.3'
-gem 'spree_gateway', '~> 3.9'
-```
-
-### Run `bundle install`
-
-**Note**: if you run into `Bundler could not find compatible versions for gem "sprockets":` error message, please run
-
-```bash
-bundle update
-```
-
-### Use the install generators to set up Spree
-
-```shell
-rails g spree:install --user_class=Spree::User
-rails g spree:auth:install
-rails g spree_gateway:install
-```
+1. [Install Docker](https://docs.docker.com/get-docker/)
+2. Download [Spree Starter](https://github.com/spree/spree_starter/archive/main.zip)
+3. Unzip it
+4. Run `bin/setup` in `spree_starter-main` directory
## Upgrade