Skip to content

Commit 40bd145

Browse files
schbetsyschbetsy
committed
Consolidate "docker-compose" instructions, other cleanup
1 parent a4a26d9 commit 40bd145

File tree

1 file changed

+80
-61
lines changed

1 file changed

+80
-61
lines changed

‎README.md

Lines changed: 80 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@ For more information on HMDA, checkout the [About HMDA page](http://www.consumer
1414

1515
This repository contains the code for the entirety of the HMDA platform backend. This platform has been designed to accommodate the needs of the HMDA filing process by financial institutions, as well as the data management and publication needs of the HMDA data asset.
1616

17+
The HMDA Platform uses sbt's multi-project builds, each project representing a specific task. The platform is an Akka Cluster
18+
application that can be deployed on a single node or as a distributed application. For more information on how Akka Cluster
19+
is used, see the documentation [here](Documents/cluster.md)
20+
1721
The HMDA Platform is composed of the following modules:
1822

1923
### Parser (JS/JVM)
@@ -70,25 +74,91 @@ The HMDA Platform is written in [Scala](http://www.scala-lang.org/). To build it
7074

7175
In addition, you'll need Scala's interactive build tool [sbt](http://www.scala-sbt.org/0.13/tutorial/index.html). Please refer to sbt's [installation instructions](http://www.scala-sbt.org/0.13/tutorial/Setup.html) to get started.
7276

77+
### Docker
78+
79+
Though Docker is not a dependency of the Scala project, it is very useful for running and smoke testing locally.
80+
Use the following steps to prepare a local environment for running the Platform with docker:
81+
82+
First, make sure that you have the [Docker Toolbox](https://www.docker.com/docker-toolbox) installed.
83+
84+
If you don't have a Docker machine created, you can create one with the default parameters using the command below.
85+
This will be sufficient for running most docker containers (e.g. the dev dependencies for the API), but not for running the entire platform.
86+
87+
```shell
88+
docker-machine create --driver virtualbox dev
89+
```
90+
91+
If you wish to run the entire platform using Docker (currently the only way to run the entire platform),
92+
you'll need to dedicate more resources to the Docker machine.
93+
We've found that for the full stack to run efficiently, you need approximately:
94+
95+
* 4 CPUs
96+
* 6 GB RAM
97+
* 80 GB Disk space
98+
99+
Assuming you are using Docker Machine to provision your Docker
100+
environment, you can check you current settings with the following
101+
(ignore the second `Memory`):
102+
103+
```shell
104+
$ docker-machine inspect | grep 'CPU\|Memory\|DiskSize'
105+
"CPU": 4,
106+
"Memory": 6144,
107+
"DiskSize": 81920,
108+
"Memory": 0,
109+
```
110+
111+
If your settings are below these suggestions, you should create a new
112+
Docker VM. The following will create a VM named `hmda-platform` with
113+
the appropriate resources:
114+
115+
```shell
116+
$ docker-machine create \
117+
--driver virtualbox \
118+
--virtualbox-disk-size 81920 \
119+
--virtualbox-cpu-count 4 \
120+
--virtualbox-memory 6144 \
121+
hmda-platform
122+
```
123+
124+
After the machine is created, make sure that you connect your shell with the newly created machine
125+
```shell
126+
$ eval "(docker-machine env dev)"
127+
```
128+
129+
73130
## Building and Running
74131

75-
The HMDA Platform uses sbt's multi-project builds, each project representing a specific task. The platform is an Akka Cluster
76-
application that can be deployed on a single node or as a distributed application. For more information on how Akka Cluster
77-
is used, see the documentation [here](Documents/cluster.md)
132+
### Building the .jar
133+
134+
* To build JVM artifacts (the default, includes all projects), from the sbt prompt:
135+
136+
```shell
137+
> clean assembly
138+
```
139+
140+
This task will create a `fat jar`, which can be executed directly on any JDK8 compliant JVM:
141+
142+
```shell
143+
java -jar target/scala-2.11/hmda.jar
144+
```
145+
78146

79-
### Interactive
147+
### Running Interactively
80148

81149
#### Running the Dependencies
82150

83-
Assuming you have Docker-Compose installed, the easiest way to get all of the platform's dependencies up and running with the provided docker-compose dev setup:
151+
Assuming you have Docker-Compose installed (according to the [Docker](#docker) instructions above),
152+
the easiest way to get all of the platform's dependencies up and running with the provided docker-compose dev setup:
84153

85154
```shell
86155
docker-compose -f docker-dev.yml up
87156
```
88157

89158
When finished, use `docker-compose down` to gracefully stop the running containers.
90159

91-
Alternatively, you can start each one individually by following the instructions in the [Local Dependencies](documents/local-depencencies.md) documentation.
160+
Alternatively, you can start each one individually by following the instructions in
161+
the [Local Dependencies](documents/local-depencencies.md) documentation.
92162

93163

94164
#### Running the API
@@ -124,39 +194,14 @@ Confirm that the platform is up and running by browsing to http://localhost:8080
124194
When finished, press enter to get the sbt prompt, then stop the project by entering `reStop`.
125195

126196

127-
#### Building the Project
128197

129-
* To build JVM artifacts (the default, includes all projects), from the sbt prompt:
198+
### Running the Project with Docker
130199

131-
```shell
132-
> clean assembly
133-
```
134-
135-
This task will create a `fat jar`, which can be executed directly on any JDK8 compliant JVM:
136-
137-
```shell
138-
java -jar target/scala-2.11/hmda.jar
139-
```
140-
141-
142-
### Docker
143-
144-
First, make sure that you have the [Docker Toolbox](https://www.docker.com/docker-toolbox) installed.
145-
146-
If you don't have a Docker machine created, you can create one by issuing the following:
147-
```shell
148-
docker-machine create --driver virtualbox dev
149-
```
150-
151-
After the machine is created, make sure that you connect your shell with the newly created machine
152-
```shell
153-
$ eval "(docker-machine env dev)"
154-
```
155-
156-
Ensure there's a compiled jar to create the Docker image with:
200+
First, ensure there's a compiled jar to create the Docker image with:
157201
```shell
158202
sbt clean assembly
159203
```
204+
160205
#### To run only the API
161206

162207
Build the docker image
@@ -174,33 +219,7 @@ The Public API will run on `$(docker-machine ip):8082`
174219

175220
#### To run the entire platform
176221

177-
1. Dedicate appropriate resources to your Docker environment. We've found
178-
that for the full stack to run efficiently, you need approximately:
179-
180-
* 4 CPUs
181-
* 6 GB RAM
182-
* 80 GB Disk space
183-
184-
Assuming you are using Docker Machine to provision your Docker
185-
environment, you can check you current settings with the following
186-
(ignore the second `Memory`):
187-
188-
$ docker-machine inspect | grep 'CPU\|Memory\|DiskSize'
189-
"CPU": 4,
190-
"Memory": 6144,
191-
"DiskSize": 81920,
192-
"Memory": 0,
193-
194-
If your settings are below these suggestions, you should create a new
195-
Docker VM. The following will create a VM named `hmda-platform` with
196-
the appropriate resources:
197-
198-
$ docker-machine create \
199-
--driver virtualbox \
200-
--virtualbox-disk-size 81920 \
201-
--virtualbox-cpu-count 4 \
202-
--virtualbox-memory 6144 \
203-
hmda-platform
222+
1. Ensure you have a Docker Machine with sufficient resources, as described in the [Docker](#docker) section above.
204223

205224
1. Clone [hmda-platform-ui](https://github.com/cfpb/hmda-platform-ui) and
206225
[hmda-platform-auth](https://github.com/cfpb/hmda-platform-auth) into the same

0 commit comments

Comments
 (0)