You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/manual/gettingstarted.md
+8-2
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,14 @@
1
1
# Getting Started with Blueprint
2
2
3
-
## Run SockShop
3
+
## Prerequisites
4
4
5
-
Start with the [SockShop](../../examples/sockshop) application. The documentation of the example application describes how to compile and run the application.
5
+
To run the example applications, you will need to install the recommended [prerequisites](requirements.md).
6
+
7
+
## Applications
8
+
9
+
Blueprint has a number of out-of-the-box applications, listed in the [examples](../../examples) directory.
10
+
11
+
To get started, we will compile and run the SockShop application. Navigate to the [SockShop](../../examples/sockshop) directory and follow the directions there.
Different plugins have different pre-requisites; you only need to install the pre-requisites of a plugin if you intend to use it. That said, we recommend installing the following:
3
+
In order to compile a Blueprint application, the build machine must satisfy the pre-requisites listed here. Note that these requirements apply to the machine on which you are compiling the application; they do not typically also apply to the machine(s) on which you run the application.
4
4
5
-
* golang 1.20 or higher
6
-
* Docker
7
-
* Kubernetes
8
-
* gRPC
9
-
10
-
## Blueprint pre-requisites
5
+
## Compiler Requirements
11
6
12
7
Blueprint requires golang 1.20 or higher.
13
8
14
-
## Plugin requirements
15
-
16
-
See the respective plugin documentation in [plugins](../../plugins/) for individual plugin requirements.
17
-
18
-
### Plugin compile-time requirements
19
-
20
-
Some plugins have additional requirements necessary to compile applications that use those plugins. These requirements are optional; they are only needed if the plugin is used. Examples include:
21
-
-[gRPC plugin](../plugins/grpc) requires that the protobuf and gRPC compiler are installed
22
-
-[Thrift plugin](../plugins/thrift/) requires that Thrift is installed
23
-
24
-
Plugins are expected to document their requirements.
25
-
26
-
### Plugin runtime requirements
27
-
28
-
Some plugins do not have compilation-time requirements but do have runtime requirements. These requirements are optional; they are only needed if the plugin is used. Examples include:
29
-
-[docker-compose plugin](../plugins/dockercompose/) requires that Docker is installed in order to run docker containers
9
+
We **highly recommend** also installing the following in order to run the Blueprint examples. Follow the instructions under the **Prerequisites** heading for the following plugins:
10
+
*[gRPC](../../plugins/grpc)
11
+
*[Docker](../../plugins/docker)
12
+
*[Kubernetes](../../plugins/kubernetes)
30
13
31
-
Plugins are expected to document their requirements.
14
+
The above dependencies are sufficient for compiling most of the Blueprint example applications. However, in addition to the above, some plugins might have further dependencies that you will need to install before you can use that plugin. The plugin will document these dependencies.
Leaf is a simple application that is not representative of a real application. Its intended use is to provide examples of Blueprint API usage; it is frequently referenced by plugin documentation.
4
+
5
+
For a more realistic application to run, look at the [sockshop](../sockshop) or [dsb_sn](../dsb_sn), or other applications listed in the [examples](..) directory.
Copy file name to clipboardexpand all lines: examples/sockshop/README.md
+86-11
Original file line number
Diff line number
Diff line change
@@ -10,9 +10,7 @@ For the most part, the application directly re-uses the original SockShop code (
10
10
11
11
## Getting started
12
12
13
-
Prerequisites for this tutorial:
14
-
* gRPC and protocol buffers compiler are installed - https://grpc.io/docs/protoc-installation/
15
-
* docker is installed
13
+
Before running the example applications, make sure you have installed the recommended [prerequisites](requirements.md).
16
14
17
15
## Running unit tests prior to compilation
18
16
@@ -45,9 +43,9 @@ If you navigate to the `build` directory, you will now see a number of build art
45
43
*`build/docker/*` contain the individual docker images for services, including a Dockerfile and the golang source code
46
44
*`build/gotests` contain the unit tests that we ran in the "Running unit tests" section
47
45
48
-
## Running the application
46
+
## Configure the application
49
47
50
-
To run the application, navigate to `build/docker` and run `docker-compose up`. You might see Docker complain about missing environment variables. Edit the `.env` file in `build/docker` and put the following:
48
+
Before running the application, we must configure some ports that the application will publicly expose. Navigate to `build/docker` and create/edit the `.env` file:
To run the application, navigate to `build/docker` and run `docker-compose up`. If this is your first time running the application, this will also build the necessary container images.
70
+
71
+
## Invoke the application
72
+
73
+
The SockShop application's [frontend API](workflow/frontend) is exposed by HTTP on port 12356 (when using the above configuration).
74
+
75
+
We can invoke the `ListItems` API to list the socks in the application's catalogue:
Alternatively in your web browser navigate to [localhost:12356/ListItems?pageSize=100&pageNum=1](http://localhost:12356/ListItems?pageSize=3&pageNum=1)
69
82
70
-
## Running tests in compiled application
83
+
You should expect to see the following:
71
84
72
-
After running the application, you can run the unit tests against it.
85
+
```
86
+
{
87
+
"Ret0": [
88
+
{
89
+
"id": "3c59f984-80df-456c-8f56-6a2b57b7a342",
90
+
"name": "Classic",
91
+
"description": "Keep it simple.",
92
+
"imageUrl": [
93
+
"/catalogue/images/classic.jpg",
94
+
"/catalogue/images/classic2.jpg"
95
+
],
96
+
"price": 12,
97
+
"quantity": 127,
98
+
"tag": [
99
+
"brown",
100
+
"green"
101
+
]
102
+
},
103
+
{
104
+
"id": "4999b899-e2c7-4e61-a799-68d0778aefe8",
105
+
"name": "YouTube.sock",
106
+
"description": "We were not paid to sell this sock. It's just a bit geeky.",
107
+
"imageUrl": [
108
+
"/catalogue/images/youtube_1.jpeg",
109
+
"/catalogue/images/youtube_2.jpeg"
110
+
],
111
+
"price": 10.99,
112
+
"quantity": 801,
113
+
"tag": [
114
+
"formal",
115
+
"geek"
116
+
]
117
+
},
118
+
{
119
+
"id": "6f39c5c3-8ee8-47aa-ac7a-d5c14dcafb02",
120
+
"name": "Nerd leg",
121
+
"description": "For all those leg lovers out there. A perfect example of a swivel chair trained calf. Meticulously trained on a diet of sitting and Pina Coladas. Phwarr...",
122
+
"imageUrl": [
123
+
"/catalogue/images/bit_of_leg_1.jpeg",
124
+
"/catalogue/images/bit_of_leg_2.jpeg"
125
+
],
126
+
"price": 7.99,
127
+
"quantity": 115,
128
+
"tag": [
129
+
"blue",
130
+
"skin"
131
+
]
132
+
}
133
+
]
134
+
}
135
+
```
136
+
137
+
## Viewing Traces
138
+
139
+
Navigate to [http://localhost:12357](http://localhost:12357) to view the Zipkin WebUI.
140
+
141
+
Click the "Query" button and you should see a trace with Root "frontend_proc: listitems start". You can click "Show" to view the trace details.
142
+
143
+
## Testing the compiled application
144
+
145
+
You can run unit tests against the compiled application. After starting the application, navigate to `build/gotests/tests` and run using `go test`, passing the necessary address arguments:
73
146
74
147
```
75
148
cd build/gotests/tests
76
-
go test --payment_service.grpc.dial_addr=localhost:12346 --user_service.grpc.dial_addr=localhost:12347 --cart_service.grpc.dial_addr=localhost:12348 --order_service.grpc.dial_addr=localhost:12349 --shipping_service.grpc.dial_addr=localhost:12351 --catalogue_service.grpc.dial_addr=localhost:12355 --frontend.grpc.dial_addr=localhost:12356 --zipkin.dial_addr=localhost:12357
149
+
go test --payment_service.grpc.dial_addr=localhost:12346 --user_service.grpc.dial_addr=localhost:12347 --cart_service.grpc.dial_addr=localhost:12348 --order_service.grpc.dial_addr=localhost:12349 --shipping_service.grpc.dial_addr=localhost:12351 --catalogue_service.grpc.dial_addr=localhost:12355 --frontend.http.dial_addr=localhost:12356 --zipkin.dial_addr=localhost:12357
77
150
```
78
151
79
-
To see traces of the requests issued by the tests, navigate to[http://localhost:12357](http://localhost:12357)
152
+
The tests will also generate Zipkin traces which you can view in the Zipkin WebUI at[http://localhost:12357](http://localhost:12357).
Package docker defines compiler interfaces for use by plugins that generate and instantiate Docker images. The package does not provide any wiring spec functionality and is not directly used by Blueprint applications; only by other Blueprint plugins.
9
+
Package docker defines compiler interfaces for use by plugins that generate and instantiate Docker images.
10
+
11
+
### Prerequisites
12
+
13
+
In order to compile an application that uses Docker, the build machine must have Docker installed. Follow the instructions on the [Docker website](<https://docs.docker.com/engine/install/>). The person writing these instructions was using version 24.0.7.
14
+
15
+
### Wiring Spec Usage
16
+
17
+
The package does not provide any wiring spec functionality and is not directly used by Blueprint applications; only by other Blueprint plugins.
10
18
11
19
The noteworthy interfaces are as follows:
12
20
@@ -32,7 +40,7 @@ Consult the following plugins for examples:
32
40
33
41
34
42
<aname="Container"></a>
35
-
## type [Container](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L37-L40>)
43
+
## type [Container](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L46-L49>)
36
44
37
45
An IRNode interface that represents containers. If an IRNode implements this interface then it enables that IRNode to be instantiated within container namespaces such as docker\-compose files and Kubernetes pods.
38
46
@@ -44,7 +52,7 @@ type Container interface {
44
52
```
45
53
46
54
<aname="ContainerWorkspace"></a>
47
-
## type [ContainerWorkspace](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L81-L129>)
55
+
## type [ContainerWorkspace](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L90-L138>)
48
56
49
57
[ContainerWorkspace](<#ContainerWorkspace>) receives container images and instances from [Container](<#Container>) nodes during Blueprint's compilation process.
50
58
@@ -103,7 +111,7 @@ type ContainerWorkspace interface {
103
111
```
104
112
105
113
<aname="ContainerWorkspaceInfo"></a>
106
-
## type [ContainerWorkspaceInfo](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L69-L72>)
114
+
## type [ContainerWorkspaceInfo](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L78-L81>)
107
115
108
116
Metadata about the local build environment used during the compilation process
109
117
@@ -115,7 +123,7 @@ type ContainerWorkspaceInfo struct {
115
123
```
116
124
117
125
<aname="ProcessWorkspace"></a>
118
-
## type [ProcessWorkspace](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L138-L171>)
126
+
## type [ProcessWorkspace](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L147-L180>)
119
127
120
128
ProcessWorkspace enables \[linux.Process\] nodes to add custom Dockerfile commands when the process is being added to a Docker container. ProcessWorkspaces extends \[linux.ProcessWorkspace\] with the method \[ProcessWorkspace.AddDockerfileCommands\].
121
129
@@ -159,7 +167,7 @@ type ProcessWorkspace interface {
159
167
```
160
168
161
169
<aname="ProvidesContainerImage"></a>
162
-
## type [ProvidesContainerImage](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L50-L54>)
170
+
## type [ProvidesContainerImage](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L59-L63>)
163
171
164
172
An optional interface for Container IRNodes to implement if the node needs to generate custom container images \(e.g. using a Dockerfile\). \[target\] provides methods for doing so.
165
173
@@ -172,7 +180,7 @@ type ProvidesContainerImage interface {
172
180
```
173
181
174
182
<aname="ProvidesContainerInstance"></a>
175
-
## type [ProvidesContainerInstance](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L60-L64>)
183
+
## type [ProvidesContainerInstance](<https://github.com/blueprint-uservices/blueprint/blob/main/plugins/docker/ir.go#L69-L73>)
176
184
177
185
An optional interface for Container IRNodes to implement if the node wants to declare an instance of a container. The container instance can be of a pre\-existing image or of a locally\-defined image that was declared with [ProvidesContainerImage](<#ProvidesContainerImage>).
0 commit comments