docs-source/docs/modules/microservices-tutorial/pages/template.adoc

= Section 2: Start a project
:page-supergroup-java-scala: Language

include::ROOT:partial$include.adoc[]


We provide a template so that you don't need to create the shopping cart project structure along with configuration and build files. The instructions below describe how to run the template and open the resulting project in IntelliJ. If you are using a different IDE, substitute as necessary.

== Akka Workshop
The video based https://info.lightbend.com/akka-platform-workshop-part-1-on-demand-recording.html[Akka Workshop Series {tab-icon}, window="tab"] series will walk you through starting a project.

:sectnums:

[#seed-template]
== Download the empty template

The starting template is available as downloadable zip file with Java or Scala sources. Select your preferred language (Java/Scala):

[.tabset]
Java::
+
Download link:_attachments/0-shopping-cart-start-java.zip[Java sources].

Scala::
+
Download link:_attachments/0-shopping-cart-start-scala.zip[Scala sources].

Unzip the file and you should have 3 directories:

* `shopping-analytics-service`
* `shopping-cart-service`
* `shopping-order-service`

In the first part of the tutorial we will work with the `shopping-cart-service` and we will use the others in later steps of the tutorial.

Change to the new `shopping-cart-service` project directory and try to build it with:

[.tabset]
Java::
+
----
mvn compile
----

Scala::
+
----
sbt compile
----

ifdef::review[REVIEWERS: we should add what they will see if successful and what to do if not.]

[#intellij]
== Open the project in IntelliJ

If you are using IntelliJ, follow these steps to open the project:

. From  the *File > Open* menu, select [.group-scala]#`shopping-cart-service/build.sbt`# [.group-java]#`shopping-cart-service/pom.xml`#.
. Select *Open as project*.

ifdef::review[REVIEWERS: is this the appropriate place to run Docker, or wait until they have created their first service and are trying to run it?]

== Run Docker and Docker Compose

Follow these steps to prepare for running shopping cart:

// # tag::docker[]
. From the root project directory, run the following command:
+
[source,shell script]
----
docker-compose up -d
----
This command will build and run the containers. The `-d` flag starts the containers in detached mode. Containers started in detached mode exit when the root process used to run the container exits
. Create the PostgresSQL tables from the SQL script located inside the `ddl-scripts` at the root of the project:
+
[source,shell script]
----
docker exec -i shopping-cart-service_postgres-db_1 psql -U shopping-cart -t < ddl-scripts/create_tables.sql
----
+
It creates all tables needed for Akka Persistence as well as the offset store table for Akka Projection.
+
include::partial$docker-important.adoc[]
+

// # end::docker[]

:!sectnums:

== Configuration for local development

The template contains configuration files for local development. We will be using them in the procedures that follow, but this section provides an overview. 

By default, when using [.group-scala]#`sbt run`# [.group-java]#`mvn exec:exec`# the `Main` class will start an `ActorSystem` with `application.conf` which is the configuration intended to be used in production. When running Microservices locally each service must use unique Akka port numbers when running on the same machine.

To simplify the process of running multiple nodes locally, we've provided three configuration files named `local1.conf`, `local2.conf`, and `local3.conf` with the port values shown below. All of the local configuration files include `application.conf`.

You can override the configuration by passing one of the provided `local` configuration files to the build tool using a `-D` option.

For example, once a piece of functionality is complete, you can run one Akka Cluster node with `local1.conf` as follows:

[.group-java]
[source,shell script]
----
# make sure to compile before running exec:exec
mvn compile exec:exec -DAPP_CONFIG=local1.conf
----

[.group-scala]
[source,shell script]
----
sbt -Dconfig.resource=local1.conf run
----

Then, on separate terminal windows, you can start two additional nodes with `local2.conf` and `local3.conf`:

[.group-java]
[source,shell script]
----
# On a second terminal run:
#   (make sure to compile before running exec:exec)
mvn compile exec:exec -DAPP_CONFIG=local2.conf

# On a third terminal run:
mvn compile exec:exec -DAPP_CONFIG=local3.conf
----

[.group-scala]
[source,shell script]
----
# On a second terminal run:
sbt -Dconfig.resource=local2.conf run


# On a third terminal run:
sbt -Dconfig.resource=local3.conf run
----

The local configuration files set the following ports for each of the example services:

.shopping-cart-service ports
|===
|Node |Akka Cluster |Akka Management HTTP |Akka gRPC

|local1.conf
|2551
|9101
|8101

|local2.conf
|2552
|9102
|8102

|local3.conf
|2553
|9103
|8103

|===

.shopping-analytics-service ports
|===
|Node |Akka Cluster |Akka Management HTTP |Akka gRPC

|local1.conf
|3551
|9201
|-

|local2.conf
|3552
|9202
|-

|local3.conf
|3553
|9203
|-

|===

.shopping-order-service ports
|===
|Node |Akka Cluster |Akka Management HTTP |Akka gRPC

|local1.conf
|4551
|9301
|8301

|local2.conf
|4552
|9302
|8302

|local3.conf
|4553
|9303
|8303

|===