Things you need to know before starting with Open Commerce
Introduction
In a nutshell what Open Commerce is:
- A backend/GraphQL API
- An admin written with meteor
- An example frontend (which now is NextJS based) and you can either build on top or rewrite from scratch
The Dockerized environments are custom NodeJS pre-built images of each module, but you can change them to be development environments with make
.
On top of this core, you have a proudly invented elsewhere Hydra authentication system.
Getting a bit deeper
These are some things I would have like to be told before starting with Open Commerce (formerly Reaction Commerce):
- The idea behind current documentation is to have you running a full local development environment (heavily based on Docker) on your machine. The silver line is that once that’s ready you can develop plugins.
- To do this the main thing is to clone reaction development git repo and simply run
make
. What you need before running make is to have:make
, Docker (either Desktop or Engine) and docker-compose installed locally. - The whole system is built using
make
. See the project documentation list of commands to see the details. But in a nutshell, it allows you to build, start, stop, re-build, build partially, run on development mode, and more. - The most important make commands are:
make
,make start
andmake stop
. If nothing wrong happens, that should be it to get you experiencing Open Commerce locally. - Debugging problems will require some Docker knowledge and get a bit more familiar with the commerce stack. Even though you have to orchestrate it all, you can work with the individual parts. In the next section, I will share some general rules and tools.
- The system packs lots of stuff that’s pre-configured for Reaction, but in reality, you have separate projects. Even reaction has separate parts. Use the Open Commerce Quick Start to get things ready and if you want more details about its parts.
What you should be running after make
finishes its job is a number of docker instances. If you run docker ps -a
you should get the following IMAGE names (I will omit the versions):
- reactioncommerce/example-storefront: This is the example storefront that your buyers would visit.
- reactioncommerce/identity: Together with Hydra allows authentication of administrators and buyers.
- oryd/hydra: This is a separate project integrated with Open Commerce which together with identity (above) provides authentication.
- reactioncommerce/admin: This is the store backend. You can create products, manage orders, etc…
- reactioncommerce/reaction: The GraphQL API server that drives the shop.
- mongo: Required for the reaction GraphQL API server.
- postgres: Required for Hydra to work.
All of these containers need to be up and running for you to use the system. And if you don’t install anything else, the URLs you’ll be interested in are:
- First, your shop will run from localhost:4000
- At localhost:4080 you’ll be able to login into the admin interface
- And maybe localhost:3000/graphql which lets you interact directly with the API
There are more ports and stuff, but those are the interesting ones.
Dealing with problems
If something went wrong it could mean a lot of things. There are way too many moving parts to cover all the bases, but I will focus on getting some information out of the Dockerized containers.
Most important thing is to have all the containers running, if one is not running you can deal with it manually. Even though make
orchestrates it all, everything is separate and you can deal with it individually.
Each top container has a directory within the cloned repo. For example, the reactioncommerce/admin container has a reaction-admin directory. Within this directory, you have a docker-compose.yml file that describes the container. This means in this directory you can run the following commands:
bin/setup
: This is a bash script that does all necessary tasks to get the container running.docker-compose up -d
: Same as above, but you get detached from the container console. This means you won’t be able to read error messages.docker-compose down
: Useful to stop manually the container
All of these are useful but could be replaced by make
reaction commands. Having said that, there are a couple more commands which you’ll find useful:
docker-compose up
: This will start the container (if it is the first time, it will also build it).docker-compose logs -f
: This lets you see the container logs. This is useful to debug.
In both cases, it will show you the console of the container which gives a lot of useful debugging information. When combined with the other 3 it allows you to debug a bit more what might be wrong with the container.
Currently, the original documentation is being revamped and most pages redirect you to the Mailchimp Open Commerce succinct instructions. So if you need in depths docs I suggest you download reaction-docs @ github and run locally:
git clone git@github.com:reactioncommerce/reaction-docs.git
cd reaction-docs
bin/setup
docker-compose up
Then open localhost:4242 and you’ll have a good source of in-depth information about the platform.
The community also has a discord channel that you can visit.
This article discusses a development environment, for a production environment you will need a different setup. The community provides a Traefik receipe which can work and I will discuss in a future article.
Hopefully, this blog post will help you with your first steps.