Skip to content

Commit 6069f09

Browse files
biniona-mongodbbiniona-mongodb
authored
(DOCSP-23757) Updates to Readme From Pilot Test (#1265)
* readme updates * fix readme numbering * proofread, spell-check, grammar-check * feedback wip * feedback - wip * feedback - wip * jd - restructure * jd - restructure edit * add intro text * spell-check, grammar-check * test new venv command * add tip about help command. * proofread
1 parent 1121ac3 commit 6069f09

File tree

4 files changed

+167
-83
lines changed

4 files changed

+167
-83
lines changed

‎source/includes/sample_apps/csfle/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
**/obj/
22
build/**/test/**
3+
in_use_encryption_env/**
34
.envrc
45
**/master-key.txt
56
**/libmongocrypt/

‎source/includes/sample_apps/csfle/README.md

Lines changed: 164 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,84 +1,166 @@
11
# Sample CSFLE Applications
22

3-
1. Run `cp envrc_template .envrc` and then fill out your `.envrc` file. You can fill out the `.envrc` file by using
4-
the DBX team's test credentials, or by creating accounts
5-
on KMS each KMS provider and filling in the file.
6-
7-
2. Use `direnv` to load the environment variables defined in your `.envrc` file into your environment.
8-
9-
3. Install python packages by running `pip install -r requirements.txt`
10-
11-
> **_NOTE:_** If you must test new QE/FLE fetures in python, run `source python-fle-2 requirements.sh` to build and install `pymongo` and `pymongo-crypt` from source.
12-
13-
4. Install bluehawk by running `npm install -g bluehawk`
14-
15-
5. Run `python build.py` to generate scripts to create a DEK and insert a sample document in all combinations of the following languages and KMS providers:
16-
17-
- Local Key Provider
18-
- AWS KMS
19-
- GCP KMS
20-
- Azure Key Vault
21-
22-
- Dotnet
23-
- Node
24-
- Python
25-
- Java
26-
- Go
27-
28-
Once you build the files, you should see a `build` directory with the following structure:
29-
30-
```
31-
build
32-
├── dotnet
33-
│   ├── aws
34-
│   │   ├── reader
35-
│   │   └── test
36-
│   ├── azure
37-
│   │   ├── reader
38-
│   │   └── test
39-
│   ├── gcp
40-
│   │   ├── reader
41-
│   │   └── test
42-
│   └── local
43-
│   ├── reader
44-
│   └── test
45-
├── go
46-
│   ├── aws
47-
│   │   ├── reader
48-
│   │   └── test
49-
│   ├── azure
50-
│   │   ├── reader
51-
│   │   └── test
52-
│   ├── gcp
53-
│   │   ├── reader
54-
│   │   └── test
55-
│   └── local
56-
│   ├── reader
57-
│   └── test
58-
├── java
59-
│   ├── aws
60-
│   │   ├── reader
61-
│   │   └── test
62-
│   ├── azure
63-
│   │   ├── reader
64-
│   │   └── test
65-
│   ├── gcp
66-
│   │   ├── reader
67-
│   │   └── test
68-
│   └── local
69-
│   ├── reader
70-
│   └── test
71-
...
72-
```
73-
74-
The `reader` directories contains the code to use in docs code snippets, and the `test` directories contains runnable examples for testing.
75-
76-
6. Install the following languages and tools necessary
77-
to run sample applications:
78-
79-
- [JDK](https://dotnet.microsoft.com/en-us/download) and [Maven](https://maven.apache.org/download.cgi)
80-
- [Dotnet SDK](https://dotnet.microsoft.com/en-us/download)
81-
- [Node](https://nodejs.org/en/download/)
82-
- [Go](https://go.dev/dl/)
83-
84-
7. Run `python -m unittest test.py` to test the generated scripts using the KMS credentials in your `.envrc` file.
3+
This README details how to build and test the sample applications
4+
for In Use encryption (Client-Side Field Level Encryption (CSFLE) and Queryable Encryption (QE)).
5+
6+
## Install Packages:
7+
8+
1. Download and set up `direnv`. Follow these links for instructions:
9+
10+
- [Download](https://direnv.net/)
11+
- [Setup](https://direnv.net/docs/hook.html)
12+
13+
1. Install bluehawk by running `npm install -g bluehawk`
14+
15+
1. Download the following tools necessary to run FLE/QE:
16+
17+
- libmongocrypt (latest, experimental version). Run:
18+
19+
```
20+
brew uninstall libmongocrypt
21+
brew install libmongocrypt --head
22+
```
23+
24+
- enterprise server and mongocryptd
25+
26+
- Install from the [downloads](https://www.mongodb.com/try/download/enterprise) site
27+
28+
- crypt_shared
29+
30+
- Install from the [downloads](https://www.mongodb.com/try/download/enterprise) site
31+
32+
> **_NOTE:_** Ensure you are running/using MongoDB Enterprise, mongocryptd, and `crypt_shared` versions 6.0.0-rc8 or greater. If you run any of these tools with a release less than 6.0.0-rc8, Queryable Encryption will fail.
33+
34+
1. Install [`mlaunch`](http://blog.rueckstiess.com/mtools/mlaunch.html)
35+
36+
1. Install the following languages and tools necessary
37+
to run and format the sample applications:
38+
39+
- [JDK](https://www.oracle.com/java/technologies/downloads/) and [Maven](https://maven.apache.org/download.cgi)
40+
- [Dotnet SDK](https://dotnet.microsoft.com/en-us/download)
41+
- [Node](https://nodejs.org/en/download/) and [Prettier](https://prettier.io/docs/en/install.html)
42+
- [Go](https://go.dev/dl/)
43+
44+
> **_TIP:_** If you do not yet have a Java and Maven environment setup, this may be the hardest to get working. Ensure you set your `$JAVA_HOME` environment variable.
45+
46+
Run the following commands to test that you installed all tools:
47+
48+
```
49+
dotnet --version
50+
node --version
51+
java --version
52+
mvn --version
53+
python --version
54+
go version
55+
prettier --version
56+
```
57+
58+
## Configure Environment
59+
60+
1. Create a three-node replica set with the following command:
61+
62+
```
63+
mlaunch --replicaset --nodes 3
64+
```
65+
66+
1. Clone the `docs_mongodb_internal` repository and `cd` into the directory that contains this `README` file.
67+
68+
1. Run `cp envrc_template .envrc` and then fill out your `.envrc` file. You can fill out the `.envrc` file by using the DBX team's test credentials, or by creating accounts on each KMS provider. Ask someone who already has these credentials to send them to you over 0bin. If you do not know anyone with these credentials, contact the DBX team and request these credentials.
69+
70+
> **_NOTE:_** Do not fill out the `envrc_template` file. File out the `.envrc` file you create with the `cp` command.
71+
72+
> **_TIP:_** Your `MONGODB_URI` environment variable must contain the URI of the replica set you started with the `mlaunch` command.
73+
74+
> **_TIP:_** Your `SHARED_LIB_PATH` environment variable must point to the location of `mongo_crypt_v1.dylib` included in your `crypt_shared` download.
75+
76+
1. Run `direnv allow` from the directory that contains this `README` file to load the environment variables defined in your `.envrc` file into your environment.
77+
78+
> **_NOTE:_** When `direnv` is working, you will see the environment variables echoed back to you when entering into the sample app directory:
79+
>
80+
> ```
81+
> ...
82+
> direnv: loading .../.envrc
83+
> direnv: export +AWS_ACCESS_KEY_ID +AWS_KEY_ARN ...
84+
> ```
85+
86+
1. Create a python virtual environment to install dependencies and ensure you are running python 3.6 or greater:
87+
88+
```
89+
python3.6 -m venv in_use_encryption_env && source in_use_encryption_env/bin/activate
90+
pip install --upgrade pip
91+
```
92+
93+
1. Install python packages by running `pip install -r requirements.txt`
94+
95+
> **_NOTE:_** If you must test new QE/FLE features in python, run `source python-fle-2/requirements.sh` to build and install `pymongo` and `pymongo-crypt` from source.
96+
97+
## Build Applications
98+
99+
1. Run `python build.py` to generate scripts to create a DEK and insert a sample document in all combinations of the following languages and KMS providers:
100+
101+
- Local Key Provider
102+
- AWS KMS
103+
- GCP KMS
104+
- Azure Key Vault
105+
106+
- Dotnet
107+
- Node
108+
- Python
109+
- Java
110+
- Go
111+
112+
Once you build the files, you should see a `build` directory with the following structure:
113+
114+
```
115+
build
116+
├── dotnet
117+
│   ├── aws
118+
│   │   ├── reader
119+
│   │   └── test
120+
│   ├── azure
121+
│   │   ├── reader
122+
│   │   └── test
123+
│   ├── gcp
124+
│   │   ├── reader
125+
│   │   └── test
126+
│   └── local
127+
│   ├── reader
128+
│   └── test
129+
├── go
130+
│   ├── aws
131+
│   │   ├── reader
132+
│   │   └── test
133+
│   ├── azure
134+
│   │   ├── reader
135+
│   │   └── test
136+
│   ├── gcp
137+
│   │   ├── reader
138+
│   │   └── test
139+
│   └── local
140+
│   ├── reader
141+
│   └── test
142+
├── java
143+
│   ├── aws
144+
│   │   ├── reader
145+
│   │   └── test
146+
│   ├── azure
147+
│   │   ├── reader
148+
│   │   └── test
149+
│   ├── gcp
150+
│   │   ├── reader
151+
│   │   └── test
152+
│   └── local
153+
│   ├── reader
154+
│   └── test
155+
...
156+
```
157+
158+
The `reader` directories contain the code to use in docs code snippets, and the `test` directories contain runnable examples for testing.
159+
160+
> **_TIP:_** To see all options available in the `build.py` script, run `python build.py --help`.
161+
162+
## Test Applications
163+
164+
1. Run `python -m unittest test.py` to test the generated scripts using the KMS credentials in your `.envrc` file.
165+
166+
> **_TIP:_** To test an individual language, run the following command: `python -m unittest test.<test class name>`. For example to, test the Python CSFLE application, run `python -m unittest test.TestPython`. You can see a list of all test classes in the `test.py` file.

‎source/includes/sample_apps/csfle/dotnet/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,4 @@ To build Dotnet applications, run the following command from the parent of this
1313
To test your built applications, run the following
1414
command from the parent of this directory:
1515

16-
python -m unittest test.TestDotNet
16+
python -m unittest test.TestDotnet

‎source/includes/sample_apps/csfle/requirements.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,3 +11,4 @@ pycparser==2.21
1111
pymongocrypt
1212
tomli==2.0.1
1313
typing_extensions==4.2.0
14+
mtools

0 commit comments

Comments
 (0)