Merge pull request #2433 from benjaminwil/getting_started_documentation

Getting started documentation

guides/getting-started/develop-solidus.md

@@ -0,0 +1,122 @@
+# Develop Solidus
+
+If you would like to develop for Solidus and you intend to submit your work as a
+pull request, please [read the contributing guidelines][contributing] first.
+
+Getting your Solidus development environment set up is easy. First, clone the
+Solidus GitHub repo:
+
+```shell
+git clone git://github.com/solidusio/solidus.git
+```
+
+Then enter the directory you just downloaded and install Solidus's dependencies:
+
+```shell
+cd solidus
+bundle install
+```
+
+## Create a sandbox application
+
+Solidus is meant to be run within a Rails application. You can create a sandbox
+application inside the source directory that you have cloned. This gives you a
+typical Solidus store you can use for testing.
+
+By default, the sandbox includes [`solidus_auth_devise`][solidus-auth-devise],
+and the generator seeds the database and loads sample data.
+
+```shell
+bundle exec rake sandbox
+```
+
+You can prepend `DB=mysql` or `DB=postgresql` to the command in order use those
+databases instead of the default SQLite 3 database. For example:
+
+```shell
+DB=postgresql bundle exec rake sandbox
+``` 
+
+After the sandbox has been generated, you can change into its directory and
+start the server:
+
+```
+cd sandbox
+rails server
+```
+
+[contributing]: https://github.com/solidusio/solidus/blob/master/CONTRIBUTING.md
+[solidus-auth-devise]: https://github.com/solidusio/solidus_auth_devise
+
+## Testing
+
+Solidus uses [RSpec](http://rspec.info/) for testing. Refer to its documentation
+for more information about the testing library.
+
+If you intend to submit your work to Solidus as a pull request, it must pass all
+of the Solidus test suites before it is merged. You must also provide new or
+updated tests for your features or bug fixes.
+
+We use CircleCI to run tests on all incoming pull requests.
+
+To run the test suites for `solidus_frontend` and `solidus_backend`, you need to
+install [ChromeDriver][chomedriver] on your system first.
+
+You can see the build statuses [on our CircleCI status page][circleci].
+
+### Run all Solidus test suites
+
+To execute all of the test specs, run the `build.sh` script at the root of the
+Solidus project:
+
+```shell
+bash build.sh
+```
+
+This runs using PostgreSQL by default, but it can be overridden by setting the
+`DB` environment variable to `DB=sqlite` or `DB=mysql`. For example: 
+
+```shell
+DB=mysql bash build.sh
+```
+
+Note that this will fail if you have not installed ChromeDriver on your system.
+
+### Run a single test suite
+
+Each gem contains its own test suite. For example, you can run only the
+`solidus_core` gem tests within the `/core` directory:
+
+```shell
+cd core
+bundle exec rspec
+```
+
+By default, the tests run against the default SQLite 3 database. You can instead
+specify `DB=mysql` or `DB=postgresql` by prepending it to the command:
+
+```shell
+DB=postgresql bundle exec rspec
+```
+
+### Generate a code coverage report
+
+You can generate a [SimpleCov](https://github.com/colszowka/simplecov) code
+coverage report by prepending `COVERAGE=true` to the `rspec` command:
+
+```shell
+COVERAGE=true bundle exec rspec
+```
+
+## Develop a Solidus extension
+
+You can add additional features to your store using Solidus extensions. A list
+of supported extensions can be found at [extensions.solidus.io][extensions].
+
+You can use the [`solidus_cmd`][solidus-cmd] gem if you want to start creating a
+new Solidus extension.
+
+[chromedriver]: https://sites.google.com/a/chromium.org/chromedriver/home
+[circleci]: https://circleci.com/gh/solidusio/solidus
+[extensions]: https://extensions.solidus.io
+[solidus-cmd]: https://github.com/solidusio/solidus_cmd

guides/getting-started/first-time-installation.md

@@ -0,0 +1,256 @@
+# First-time installation
+
+This article will help you install and run Solidus on your local machine for the
+first time. This guide is aimed specifically at developers running macOS. 
+
+If you run Linux or Windows, or you don't use [Homebrew][brew] on your Mac, you
+can still follow this guide. However, you may want to consult other
+documentation while installing Ruby, SQLite 3, and other dependencies on your
+system.
+
+[brew]: https://brew.sh
+
+## Getting help
+
+If you're following this guide and still having trouble installing Solidus,
+[join the Solidus Slack team][slack-invitation] and start a conversation
+in the [#support channel][slack-support].
+
+If you are still not able to get Solidus running, [open an issue on
+GitHub][solidus-github-issue] with any information you think would help to
+reproduce the issues you're having. That would include your operating system and
+its version, the versions of Ruby, Rails, and SQLite 3 that you are running, and
+the specific error messages you are receiving during installation. 
+
+[solidus-github-issue]: https://github.com/solidusio/solidus/issues/new
+[slack-invitation]: http://slack.solidus.io
+[slack-support]: https://solidusio.slack.com/messages/supports/details/
+
+## Before you start
+
+Solidus is an ecommerce platform built with [Ruby on
+Rails](http://rubyonrails.org). To get the most out of Solidus, we recommend
+that you familiarize yourself with Ruby on Rails, as well as [the Ruby
+programming language](https://www.ruby-lang.org/) beforehand.
+
+Because Solidus is an Rails engine, much of what the [Rails Guide on
+Engines](http://guides.rubyonrails.org/engines.html) explains applies directly
+to Solidus, too.
+
+We also recommend configuring your development environment so that you can
+[install RubyGems without `sudo`][gem-install-without-sudo].
+
+[gem-install-without-sudo]: https://www.michaelehead.com/2016/02/06/installing-gems-without-sudo.html
+
+## System requirements
+
+The following software is required to get Solidus running:
+
+- [Ruby](https://www.ruby-lang.org) 2.2.2 or newer
+- [SQLite 3](https://sqlite.org)
+- [Rails](http://guides.rubyonrails.org/getting_started.html) 5.0.0 or newer
+- [ImageMagick](http://imagemagick.org/script/download.php)
+
+We recommend using [Homebrew][brew] to install these dependencies on your
+Mac. Throughout this article, we will use the `brew` command for installing
+system dependencies. [The Ruby documentation also recommends using
+Homebrew][ruby-homebrew] if you need to upgrade from your system's Ruby.
+
+[ruby-homebrew]: https://www.ruby-lang.org/en/documentation/installation/#homebrew
+
+### Quick start
+
+Using Homebrew, you can install all of the requirements using the following
+commands:
+
+```shell 
+brew install ruby sqlite3 imagemagick
+gem install rails
+```
+
+See more detailed installation information below.
+
+### Upgrade Ruby on macOS 
+
+If you run macOS Sierra or an older OS, you system's version of Ruby will need
+to be upgraded from 2.0.x to 2.2.2 or newer. You can check what version of Ruby
+you have installed with the following command:
+
+```shell
+ruby --version
+```
+
+The Ruby documentation recommends installing another, newer instance of Ruby
+installing another, newer instance of Ruby using Homebrew: 
+
+```shell
+brew install ruby
+```
+
+Homebrew prioritizes the Homebrew installation of Ruby (at
+`/usr/local/bin/ruby`) above the system installation (`/usr/bin/ruby`).
+
+### Install SQLite 3
+
+Rails and Solidus use SQLite 3 as the default relational database. SQLite is a
+widely-supported, lightweight way to send and receive data. Using Homebrew,
+you can install the latest version of SQLite 3 using the following command:
+
+```shell
+brew install sqlite3
+```
+
+Alternatively, you can [download the pre-compiled binary from the SQLite
+website](https://www.sqlite.org/download.html).
+
+After the installation, check that it has been installed by checking the version
+number:
+
+```shell
+sqlite3 --version
+```
+
+If all is well, this command will return a version number that looks something
+like `3.16.0 2016-11-04 19:09:39 0f3eed3324eda2a2b8d3301e5a43dc58a3a5fd5f`.
+
+### Install Rails
+
+Rails includes everything you need to build and extend a web application. Once
+you have Ruby and SQLite 3 installed on your system, you can install Rails via
+the [RubyGems](https://rubygems.org) `gem` command that comes as a part of Ruby:
+
+```shell
+gem install rails
+```
+
+This installs Rails as well as its dependencies.
+
+### Install ImageMagick
+
+ImageMagick helps you create, edit, and save to hundreds of image file formats.
+It is required to use [Paperclip](https://github.com/thoughtbot/paperclip),
+which is how Solidus currently handles file attachments. To install ImageMagick
+via Homebrew, use the command: 
+
+```shell
+brew install imagemagick
+```
+
+Alternatively, you can [download a pre-compiled binary for macOS from the
+ImageMagick website](http://imagemagick.org/script/download.php).
+
+## Setup and installation
+
+Once you have installed all of the system requirements, we can start setting up
+Solidus.
+
+### Create and configure new Rails project
+
+First, we need a new Rails project:
+
+```shell
+rails new your_solidus_project_name
+```
+
+Once the new project has finished being created, we can open the project's newly
+created `Gemfile` in a text editor and add the required Solidus gems as new
+lines:
+
+```ruby 
+gem 'solidus'
+gem 'solidus_auth_devise'
+```
+
+By requiring [`solidus`][solidus-repo] in your `Gemfile`, you are actually
+requiring all five of the core Solidus gems:
+
+- [`solidus_core`][solidus-core]
+- [`solidus_api`][solidus-api]
+- [`solidus_frontend`][solidus-frontend]
+- [`solidus_backend`][solidus-backend]
+- [`solidus_sample`][solidus-sample]
+
+All five of these gems are maintained in the [Solidus GitHub
+repository][solidus-repo]. They are documented at a [separate documentation
+site][solidus-gem-documentation].
+
+For a first-time installation, we recommend requiring `solidus` as it provides a
+fully-functioning online store. However, you may wish to only use a subset of
+the gems and create a more custom store.
+
+Once you have saved the `Gemfile`, ensure you are in your Rails project
+directory, and then install the project's dependencies using Bundler.
+
+```shell
+cd /path/to/your-solidus-project-name
+bundle install
+```
+
+[solidus-repo]: https://github.com/solidusio/solidus
+[solidus-core]: https://github.com/solidusio/solidus/tree/master/core
+[solidus-api]: https://github.com/solidusio/solidus/tree/master/api
+[solidus-frontend]: https://github.com/solidusio/solidus/tree/master/frontend
+[solidus-backend]: https://github.com/solidusio/solidus/tree/master/backend
+[solidus-sample]: https://github.com/solidusio/solidus/tree/master/sample
+[solidus-gem-documentation]: http://docs.solidus.io
+
+### Start generating Solidus configuration files
+
+After the gems have been successfully installed, you need to create the
+necessary configuration files and instructions for the database using generators
+provided by Solidus and Railties.
+
+First, run the `spree:install` generator:
+
+```shell
+bundle exec rails generate spree:install
+```
+
+This may take a few minutes to complete, and it requires some user confirmation.
+
+### Set the administrator username and password
+
+The `spree:install` generator prompts you to configure the Solidus administrator
+username and password values.
+
+The default values are as follows:
+
+- Username: `[email protected]`
+- Password: `test123`
+
+### Prepare Solidus database migrations
+
+Next, you need run the `solidus:auth:install` generator and install your
+database migrations using the following commands:
+
+```shell
+bundle exec rails generate solidus:auth:install
+bundle exec rake railties:install:migrations
+```
+
+Finally, you need to run the migrations that Railties created. This creates the
+e-commerce–friendly models that Solidus uses for its database:
+
+```shell
+bundle exec rake db:migrate
+```
+
+### Start the Rails server and use the sample store
+
+Once the database migrations have been created, you should be able to
+successfully start the Rails server and see the sample store in your browser.
+
+First, start the server:
+
+```shell
+bundle exec rails server
+```
+
+Once the server has started, you can access your store from the following URLs:
+
+- [http://localhost:3000/](http://localhost:3000/) accesses the
+  [`solidus_frontend`][solidus-frontend] storefront.
+- [http://localhost:3000/admin/](http://localhost:3000/admin/) accesses the
+  [`solidus_backend`][solidus-backend] admin area.
+
+You can browse the sample store's pages and mock products, and so on.