diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a0abdb..0c151b4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,20 @@ +# v3.0.0 + +This is the v3.0.0 release of `reaction-development-platform`. This project is designed to be quickest way to get started with the Reaction API and its supporting services in a local development environment. + +*The following Reaction projects are being released one time in coordination as v3.0.0* + +- [Reaction API](https://github.com/reactioncommerce/reaction) +- [Reaction Hydra](https://github.com/reactioncommerce/reaction-hydra) +- [Reaction Identity](https://github.com/reactioncommerce/reaction-identity) +- [Reaction Admin (beta)](https://github.com/reactioncommerce/reaction-admin) +- [Example Storefront](https://github.com/reactioncommerce/example-storefront) +- [Reaction Development Platform](https://github.com/reactioncommerce/reaction-development-platform) + +*After this release, Reaction releases will no longer be coordinated across all projects - we'll release each project independently, as needed. This means version numbers will no longer be in sync. The newest versions of each project will work together.* + +*This project, `reaction-development-platform`, will _always_ be updated when any other project is released to keep it in sync with the latest releases from all Reaction projects.* + # v2.9.1 This is patch version update coordinated with [Reaction](https://github.com/reactioncommerce/reaction), our [Example Storefront](https://github.com/reactioncommerce/example-storefront) and [reaction-hydra](https://github.com/reactioncommerce/reaction-hydra). diff --git a/Makefile b/Makefile index 1f3f3ac..f809ffa 100644 --- a/Makefile +++ b/Makefile @@ -38,16 +38,28 @@ all: init ############################################################################### ### Init-Project -### Initializes a project. Does not do common tasks shared between projects. +### Initializes a project in production mode. +### Does not do common tasks shared between projects. ############################################################################### define init-template -init-$(1): $(1) network-create prebuild-$(1) build-$(1) post-build-$(1) start-$(1) post-project-start-$(1) +init-$(1): $(1) network-create dev-unlink-$(1) prebuild-$(1) build-$(1) post-build-$(1) start-$(1) post-project-start-$(1) endef $(foreach p,$(SUBPROJECTS),$(eval $(call init-template,$(p)))) ############################################################################### -### Init Project with System -### Init project and run the post-system hook script. +### Init-Dev-Project +### Initializes a project in development mode. +### Does not do common tasks shared between projects. +############################################################################### +define init-dev-template +init-dev-$(1): $(1) network-create dev-link-$(1) prebuild-$(1) build-$(1) post-build-$(1) start-$(1) post-project-start-$(1) +endef +$(foreach p,$(SUBPROJECTS),$(eval $(call init-dev-template,$(p)))) + +############################################################################### +### Init-With-System +### Init project and run the post-system hook script. This is useful for +### initializing a single project. ### Assumes dependencies are already started. ############################################################################### define init-with-system-template @@ -55,9 +67,23 @@ init-with-system-$(1): init-$(1) post-system-start-$(1) endef $(foreach p,$(SUBPROJECTS),$(eval $(call init-with-system-template,$(p)))) +############################################################################### +### Init-Dev-with-System +### Init project and run the post-system hook script. This is useful for +### initializing a single project in development mode. +### Assumes dependencies are already started. +############################################################################### +define init-dev-with-system-template +init-dev-with-system-$(1): init-dev-$(1) post-system-start-$(1) +endef +$(foreach p,$(SUBPROJECTS),$(eval $(call init-dev-with-system-template,$(p)))) + .PHONY: init init: $(foreach p,$(SUBPROJECTS),init-$(p)) post-system-start +.PHONY: init-dev +init-dev: $(foreach p,$(SUBPROJECTS),init-dev-$(p)) post-system-start + ############################################################################### ### Targets to verify Github is configured correctly. ############################################################################### @@ -142,7 +168,7 @@ clone: github-configured $(foreach p,$(SUBPROJECTS),$(p)) ############################################################################### define git-checkout-template checkout-$(2): $(2) - cd $(2) && git checkout "$(3)" + cd $(2) && git fetch && git checkout "$(3)" endef $(foreach rr,$(SUBPROJECT_REPOS),$(eval $(call git-checkout-template,$(shell echo $(rr) | cut -d , -f 1),$(shell echo $(rr) | cut -d , -f 2),$(shell echo $(rr) | cut -d , -f 3)))) @@ -205,15 +231,64 @@ $(foreach p,$(SUBPROJECTS),$(eval $(call post-build-template,$(p)))) .PHONY: post-build post-build: $(foreach p,$(SUBPROJECTS),post-build-$(p)) +############################################################################### +### dev-unlink +### Removes the symlinks for docker-compose development +############################################################################### +define dev-unlink-template +dev-unlink-$(1): + @cd $(1) \ + && rm -f docker-compose.override.yml \ + && echo "Removed docker development symlink for $(1)" +endef +$(foreach p,$(SUBPROJECTS),$(eval $(call dev-unlink-template,$(p)))) + +.PHONY: dev-unlink +dev-unlink: $(foreach p,$(SUBPROJECTS),dev-unlink-$(p)) + +############################################################################### +### dev-link +### Overrides default symlinks for `docker-compose` using `docker-compose.dev.yml` +############################################################################### +define dev-link-template +dev-link-$(1): + @if [ -e "$(1)/docker-compose.dev.yml" ]; then \ + cd $(1) \ + && ln -sf docker-compose.dev.yml docker-compose.override.yml \ + && echo "Created docker development symlink for $(1)"; \ + fi; +endef +$(foreach p,$(SUBPROJECTS),$(eval $(call dev-link-template,$(p)))) + +.PHONY: dev-link +dev-link: $(foreach p,$(SUBPROJECTS),dev-link-$(p)) + +############################################################################### +### dev +### Starts services in development mode with +### `ln -s docker-compose.dev.yml docker-compose.override.yml; docker-compose up -d` +############################################################################### +define dev-template +dev-$(1): stop-$(1) dev-link-$(1) start-$(1) +endef +$(foreach p,$(SUBPROJECTS),$(eval $(call dev-template,$(p)))) ############################################################################### ### Start ### Starts services with `docker-compose up -d` +### +### Pull the specified image tags every time. Tags are constantly being updated +### to point to different image IDs, and there is less to debug if we can be +### reasonably to make sure that you're always starting the latest image with that tag. +### +### We are purposely running dc up even if dc pull fails. Our Meteor project DC +### config uses `image` as a desired image tag for `build` when in dev mode. But +### `dc pull` seems to have a bug where it doesn't treat it this way and tries +### to pull it. ############################################################################### define start-template start-$(1): - @cd $(1) \ - && docker-compose up -d + @cd $(1) && docker-compose pull; docker-compose up -d endef $(foreach p,$(SUBPROJECTS),$(eval $(call start-template,$(p)))) diff --git a/README.md b/README.md index 3643367..ab5de5b 100644 --- a/README.md +++ b/README.md @@ -6,25 +6,17 @@ supporting services in a local development environment. ## Features -* An ultra modern, enterprise-ready, real-time commerce platform. +* A modern, enterprise-ready, real-time commerce platform. * A microservices based architecture. * Docker based development environment. * Launched and configured with a single CLI command. -### Project Structure - -Reaction Platform is built with a microservices architecture. This project -provides the tooling to easily orchestrate the services in a local development -environment. - -Platform services will be cloned as child directories within this project. - ## Prerequisites * [GNU Make](https://www.gnu.org/software/make/) - * macos and linux users will have a suitable version bundled with the OS + * MacOS and Linux users will have a suitable version bundled with the OS * Bourne Shell and POSIX tools (sh, grep, sed, awk, etc) - * macos and linux users will have a suitable version bundled with the OS + * MacOS and Linux users will have a suitable version bundled with the OS * [Git][5] * [Docker][0] | [Docker for Mac][1] | [Docker for Windows][2] * [Node.js][3] @@ -33,30 +25,31 @@ Platform services will be cloned as child directories within this project. ## Getting started -First, clone this repository. +Clone this repository, and then run `make` in the `reaction-platform` directory. If all goes well, it will take some time to download and start all of the components, but when it's done you'll have the entire Reaction application running on your computer through Docker. Individual services are cloned as child directories within this project. ```sh git clone git@github.com:reactioncommerce/reaction-platform.git - cd reaction-platform -``` - -#### Bootstrapping - -From within the project directory run: - -```sh make ``` -This process may take some time. Behind the scenes `make` is +Behind the scenes `make` is * checking that dependencies are present -* cloning the sub projects from GitHub: [`reaction`][10], [`reaction-hydra`][12], and the [`example-storefront`][13] +* cloning sub-projects from GitHub * downloading Docker images -* building custom, project Docker images * starting services +These services will be running when the initial `make` command is complete: + +| Service | Description | +|-----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [OAuth2 Server (Hydra)][12] (http://localhost:4444) | [ORY Hydra][11] OAuth2 token server. | +| [Reaction Identity][17] (http://localhost:4100) | The OAuth2-compatible user interface for Reaction Identity, such as login and registration. | +| [Reaction API][10] (http://localhost:3000) | The Reaction API, which includes [a GraphQL endpoint](http://localhost:3000/graphql-beta). See [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/features/graphql-playground/). | +| [Reaction Admin][19] (http://localhost:4080) | A user interface for administrators and shop managers to configure shops, manage products, and process orders. | +| [Example Storefront][13] (http://localhost:4000) | An example Reaction storefront UI built with [Next.JS](https://github.com/zeit/next.js/). | + If the `make` command fails at some point, you can run or rerun it for specific services with: ```sh @@ -69,33 +62,76 @@ Example: make init-example-storefront ``` -**Bootstrapping with Particular Git Branches** +## Project Commands -The normal bootstrapping process will give you the latest released versions of the platform subprojects and is the recommended configuration for regular development. However, if you know you require a particular previous release or alternative git branch, you can take the following steps to bring up the platform with the particular versions you need. These steps are an alternative to the standard bootstrapping approach, you should do one or the other, not both. +These are the available `make` commands in the `reaction-platform` root directory. + +| Command | Description | +|---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| `make` | Bootstraps the entire Reaction development environment in Docker. Projects will use production Docker images and code. | +| `make init-` | Example: `make init-example-storefront`. Does clone/setup for a single project. | +| `make init-dev` | Boostraps the entire Reaction development environment in Docker. Projects will use development configuration. | +| `make init-dev-` | Example: `make init-dev-example-storefront`. Does clone/setup for a single project and configures it with a development configuration. | | +| `make stop` | Stops all containers. | +| `make stop-` | Example: `make stop-example-storefront`. Stops all containers for a single project. | +| `make start` | Starts all containers. | +| `make start-` | Example: `make start-example-storefront`. Starts all containers for a single project. | +| `make dev-` | Example: `make dev-example-storefront`. Starts all containers for a single project in development mode. +| `make dev-link` | Creates `docker-compose.override.yml` symlinks for development in all projects. | +| `make dev-link-` | Example: `make dev-link-example-storefront`. Creates development symlinks for a single project. | +| `make dev-unlink` | Removes `docker-compose.override.yml` symlinks from all projects. | +| `make dev-unlink-` | Example: `make dev-unlink-example-storefront`. Removes the `docker-compose.override.yml` symlink for a single project. | | +| `make rm` | Removes all containers. Volumes are not removed. | +| `make rm-` | Example: `make rm-example-storefront`. Removes all containers for a single project. Volumes are not removed. | +| `make checkout- ` | Example: `make checkout-example-storefront release-v3.0.0`. Does `git checkout` for a sub-project. See "Running Particular Git Branches" below. | +| `make clean` | Removes all containers, networks, and volumes. Any volume data will be lost. | +| `make clean-` | Example: `make clean-example-storefront`. Removes all containers, networks, and volumes for a single project. Any volume data will be lost. | + +## Running Particular Git Branches + +After you've done the "Getting Started" steps and have the latest Reaction system running, you may need to switch to and run a certain branch/tag in one or more of the sub-projects. + +To check out and run a certain branch or tag for a project, stop the project, run `make checkout- `, and then init the project again. -From the project directory run +Example: ```sh -make clone +make stop-example-storefront +make checkout-example-storefront release-v3.0.0 +make init-example-storefront ``` -Within the necessary subproject directory or directories run the `git checkout ` commands you need to get the specific subproject versions you need checked out. +If you're getting unexpected results, `cd` into the sub-project directory and do a `git pull` to verify you're on the latest commit from that branch. If you're changing code files, see the "Running From Code For Development" section below. -Example: +### Running From Code For Development + +To ensure they start quickly, all Reaction projects are configured (in their `docker-compose.yml` file) to run from the latest published Docker image. This means that if you change code files, you will not see your changes reflected in the running application. + +##### To install the whole platform in development mode: + +Run `make init-dev` (instead of `make`). + +Doing this takes time to install and will consume more resources. + +##### To switch over to development mode for a single project: ```sh -cd example-storefront -git checkout develop +make stop- +make dev-link- +make ``` -Then run the following +If you run into trouble with the above command, run `make clean-` and then `make init-dev-`. + +##### To switch back to production mode for a single project: ```sh -cd .. # cd into reaction-platform -make +make stop- +make dev-unlink- +make ``` -This will proceed with the bootstrapping process using the versions you have explicitly checked out +If you run into trouble with the above command, run `make clean-` and then `make init-`. ## Networked Services @@ -111,56 +147,37 @@ running. ### Network Naming Strategy -Platform networks in the Docker environment should be named as -`*.reaction.localhost`. The `localhost` TLD is reserved and guaranteed to not -conflict with a real TLD. - -### Network List - -| Network | Description | -| -------------------------- | ---------------------------------------------- | -| api.reaction.localhost | GraphQL and API traffic between services. | -| auth.reaction.localhost | Authentication and authorization services. | +All projects must list `reaction.localhost` as an external network in their docker-compose configuration. The `make` commands will ensure that this network exists. Choose a unique enough name for your service that you can be reasonably sure it won't conflict with another Reaction service. -## Services +When you need to communicate with one service from another over the internal Docker network, use `.reaction.localhost` as the hostname. -These services will be running when the initial `make` command is complete: - -| Service | Description | -| ------------------------------------------------- | -------------------------------------------------------------------------------------------- | -| [OAuth2 Server (Hydra)][12] (http://localhost:4444) | [ORY Hydra][11] OAuth2 token server. | -| [Reaction Meteor][10] (http://localhost:3000) | The Reaction Meteor application, which includes the server API and the Meteor UI client. | -| [Example Storefront][13] (http://localhost:4000) | An example Reaction storefront UI built with [Next.JS](https://github.com/zeit/next.js/). | - -### GraphQL Interface -After running `make start`, you should be able to explore the GraphQL API at http://localhost:3000/graphql-beta. See [GraphQL Playground](https://www.apollographql.com/docs/apollo-server/features/graphql-playground/). +## Documentation -## Project Commands +You may refer to each sub-project's README for additional operation details. -These commands are used to control the system as a whole. +| Sub-project | Description | Documentation | +| -------------------------- | ----------------------|----------------------------------------------------------------------- | +| [`reaction`][10] | GraphQL API | [Reaction API Documentation][14] | +| [`reaction-hydra`][12] | Authentication server | [Reaction Hydra Readme][16], [Ory Hydra docs][11] | +| [`reaction-identity`][17] | Identity service | [Reaction Identity Readme][18] | +| [`reaction-admin`][19] | Classic Admin UI | [Reaction Admin Readme][20] | +| [`example-storefront`][13] | Example Storefront | [Example Storefront docs][15] | -Run these commands from the `reaction-platform` project root directory. +For tips on developing with Docker, read our [Docker docs](https://docs.reactioncommerce.com/docs/installation-docker-development). -| Command | Description | -| -------------------------- | ------------------------------------------------------------------------------------- | -| `make` | Boostraps the entire Reaction development environment in Docker. | -| `make stop` | Stops all containers. | -| `make start` | Starts all containers. | -| `make rm` | Removes all containers. Volumes are not removed. | -| `make clean` | Removes all containers, networks, and volumes. Any volume data will be lost. | -| `make init-` | Example: `make init-example-storefront`. Does clone/setup for a single project. | +### Developer Certificate of Origin +We use the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) in lieu of a Contributor License Agreement for all contributions to Reaction Commerce open source projects. We request that contributors agree to the terms of the DCO and indicate that agreement by signing-off all commits made to Reaction Commerce projects by adding a line with your name and email address to every Git commit message contributed: +``` +Signed-off-by: Jane Doe +``` -## Documentation +You can sign-off your commit automatically with Git by using `git commit -s` if you have your `user.name` and `user.email` set as part of your Git configuration. -You may refer to each sub-project's README for additonal operation details. +We ask that you use your real full name (please no anonymous contributions or pseudonyms) and a real email address. By signing-off your commit you are certifying that you have the right to submit it under the [GNU GPLv3 Licensed](./LICENSE.md). -| Sub-project | Documentation | -| ------------ | ---------------------------------------------------------------------------- | -| `reaction` | [Reaction Documentation][14] | -| `reaction-hydra` | [`reaction-hydra`][12], [`ory/hydra`][11] | -| `example-storefront` | [Example Storefront docs][15] +We use the [Probot DCO GitHub app](https://github.com/apps/dco) to check for DCO sign-offs of every commit. -For tips on developing on Docker, read our [Docker docs](https://docs.reactioncommerce.com/docs/installation-docker-development). +If you forget to sign-off your commits, the DCO bot will remind you and give you detailed instructions for how to amend your commits to add a signature. ## License @@ -176,9 +193,14 @@ Copyright © [GNU General Public License v3.0](./LICENSE.md) [7]: https://github.com/settings/keys "GitHub SSH Keys" [8]: https://github.com/reactioncommerce/reaction-platform "Reaction Platform" [9]: https://github.com/graphcool/graphql-playground "GraphQL Playground" -[10]: https://github.com/reactioncommerce/reaction "Reaction" +[10]: https://github.com/reactioncommerce/reaction "Reaction API" [11]: https://github.com/ory/hydra "ORY Hydra" [12]: https://github.com/reactioncommerce/reaction-hydra "Reaction Hydra" [13]: https://github.com/reactioncommerce/example-storefront "Example Storefront" [14]: https://docs.reactioncommerce.com "Reaction Documentation" [15]: https://github.com/reactioncommerce/example-storefront/tree/master/docs "Example Storefront docs" +[16]: https://github.com/reactioncommerce/reaction-hydra/blob/master/README.md "Reaction Hydra Readme" +[17]: https://github.com/reactioncommerce/reaction-identity "Reaction Identity" +[18]: https://github.com/reactioncommerce/reaction-identity/blob/trunk/README.md "Reaction Identity Readme" +[19]: https://github.com/reactioncommerce/reaction-admin "Reaction Admin" +[20]: https://github.com/reactioncommerce/reaction-admin/blob/trunk/README.md "Reaction Admin Readme" diff --git a/config.mk b/config.mk index ced14c1..b9aab06 100644 --- a/config.mk +++ b/config.mk @@ -27,16 +27,16 @@ endef # TAG is the git tag or branch to checkout # Projects will be started in this order define SUBPROJECT_REPOS -git@github.com:/reactioncommerce/reaction-hydra.git,reaction-hydra,v2.9.1 \ -git@github.com:/reactioncommerce/reaction.git,reaction,v2.9.1 \ -git@github.com:/reactioncommerce/example-storefront.git,example-storefront,v2.9.1 +git@github.com:/reactioncommerce/reaction-hydra.git,reaction-hydra,v3.0.0 \ +git@github.com:/reactioncommerce/reaction.git,reaction,v3.0.0 \ +git@github.com:/reactioncommerce/reaction-identity.git,reaction-identity,v3.0.0 \ +git@github.com:/reactioncommerce/reaction-admin.git,reaction-admin,v3.0.0-beta.4 \ +git@github.com:/reactioncommerce/example-storefront.git,example-storefront,v3.0.0 endef # List of user defined networks that should be created. define DOCKER_NETWORKS -auth.reaction.localhost \ -api.reaction.localhost \ -streams.reaction.localhost +reaction.localhost endef HOOK_DIR=.reaction/project-hooks