Skip to content

Commit 3c1c9c5

Browse files
kkloberdanzkevinAlbs
kkloberdanz
and
kevinAlbs
authored
add release notes to update Docker Hub overview (#1040)
* add release notes to update Docker Hub overview --------- Co-authored-by: Kevin Albertson <[email protected]>
1 parent d9ee4f8 commit 3c1c9c5

File tree

2 files changed

+328
-0
lines changed

2 files changed

+328
-0
lines changed

‎etc/releasing.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,15 @@ Finally, push the image:
321321
$ docker push mongodb/mongo-cxx-driver:<VERSION NUMBER>-redhat-ubi-9.2
322322
```
323323

324+
Update the `Tags` section of the Docker Hub
325+
[Overview](https://hub.docker.com/r/mongodb/mongo-cxx-driver) to list the latest
326+
tag and link it to the corresponding `Dockerfile` in Github. This requires privileged access to DockerHub. Ask other team members to update if you do not have access.
327+
328+
Update the `FROM` lines in each Dockerfile example such that they would pull
329+
from the latest Docker Hub image release.
330+
331+
Check in the updated overview to this repo as the file ./extras/docker/README.md
332+
324333
## Handle Linux Distribution Packages
325334

326335
Note: updates to these instructions should be synced to the corresponding C

‎extras/docker/README.md

Lines changed: 319 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,319 @@
1+
# What is MongoDB?
2+
3+
[MongoDB](https://hub.docker.com/r/mongodb/mongodb-community-server) is a
4+
cross-platform document-oriented NoSQL database. MongoDB uses JSON-like
5+
documents with optional schemas. MongoDB is developed by
6+
[MongoDB Inc](https://www.mongodb.com/).
7+
8+
This image provides both a C++ driver as well as a C driver which are used to
9+
connect to MongoDB. The C++ driver is also known as
10+
[mongo-cxx-driver](https://www.mongodb.com/docs/drivers/cxx/) and the C driver
11+
is also known as
12+
[mongo-c-driver](https://www.mongodb.com/docs/drivers/c/) or
13+
[libmongoc](https://www.mongodb.com/docs/drivers/c/).
14+
15+
# Supported tags and respective Dockerfile links
16+
17+
## Tags
18+
19+
- [3.8.1-redhat-ubi-9.2](https://github.com/mongodb/mongo-cxx-driver/blob/5b1b515e1b355943003d72a04ae47a9e0e174374/extras/docker/redhat-ubi-9.2/Dockerfile)
20+
- [3.8.0-redhat-ubi-9.2](https://github.com/mongodb/mongo-cxx-driver/blob/cb9dc3e927299bb9d2f2dc04878234e32c129685/extras/docker/redhat-ubi-9.2/Dockerfile)
21+
22+
# Examples
23+
24+
## C++ Driver Example Usage (mongo-cxx-driver)
25+
26+
First, get access to a MongoDB database server. The easiest way to do this is by
27+
using [Atlas](https://www.mongodb.com/atlas/database), where you can run an `M0`
28+
instance for
29+
[free](https://www.mongodb.com/developer/products/atlas/free-atlas-cluster/).
30+
31+
Next, create a `Dockerfile` like so.
32+
```Dockerfile
33+
# Dockerfile
34+
FROM mongodb/mongo-cxx-driver:3.8.1-redhat-ubi-9.2
35+
36+
WORKDIR /build
37+
38+
RUN microdnf upgrade -y && microdnf install -y g++
39+
40+
COPY ping.cpp /build/
41+
42+
RUN g++ \
43+
-o ping \
44+
ping.cpp \
45+
-I/usr/local/include/bsoncxx/v_noabi/ \
46+
-I/usr/local/include/mongocxx/v_noabi/ \
47+
-lmongocxx \
48+
-lbsoncxx
49+
50+
CMD /build/ping
51+
```
52+
53+
Now let's create a simple program to ping the server. Let's name this program
54+
`ping.cpp`. Notice that the connection string is stored as an environment
55+
variable and is retrieved at runtime.
56+
```C++
57+
// ping.cpp
58+
#include <cstdlib>
59+
#include <string>
60+
61+
#include <bsoncxx/json.hpp>
62+
#include <mongocxx/client.hpp>
63+
#include <mongocxx/instance.hpp>
64+
65+
std::string lookup_env(const std::string &name) {
66+
char *env = std::getenv(name.c_str());
67+
if (!env) {
68+
throw std::runtime_error("missing environment variable: " + name);
69+
}
70+
return env;
71+
}
72+
73+
int main() {
74+
try {
75+
// Create an instance.
76+
mongocxx::instance inst{};
77+
78+
std::string connection_string = lookup_env("MONGO_CONNECTION_STRING");
79+
80+
const auto uri = mongocxx::uri{connection_string};
81+
82+
// Set the version of the Stable API on the client.
83+
mongocxx::options::client client_options;
84+
const auto api = mongocxx::options::server_api{
85+
mongocxx::options::server_api::version::k_version_1};
86+
client_options.server_api_opts(api);
87+
88+
// Setup the connection and get a handle on the "admin" database.
89+
mongocxx::client conn{uri, client_options};
90+
mongocxx::database db = conn["admin"];
91+
92+
// Ping the database.
93+
const auto ping_cmd = bsoncxx::builder::basic::make_document(
94+
bsoncxx::builder::basic::kvp("ping", 1));
95+
db.run_command(ping_cmd.view());
96+
std::cout
97+
<< "Pinged your deployment using the MongoDB C++ Driver. "
98+
<< "You successfully connected to MongoDB!"
99+
<< std::endl;
100+
} catch (const std::exception &e) {
101+
// Handle errors
102+
std::cerr << "Exception: " << e.what() << std::endl;
103+
}
104+
105+
return 0;
106+
}
107+
```
108+
109+
Make sure that both `Dockerfile` and `ping.cpp` are in the same directory as
110+
each other. For example, see the directory structure below:
111+
```
112+
$ tree .
113+
.
114+
├── Dockerfile
115+
└── ping.cpp
116+
```
117+
118+
Now we need to build the Docker image. Let's name this image `mongocxx-ping`
119+
```sh
120+
docker build . -t mongocxx-ping
121+
```
122+
123+
We need to set the environment variable that contains the connection string for
124+
our database. For an Atlas cluster, you can construct the connection string like
125+
so:
126+
```
127+
'mongodb+srv://<your username here>:<your password here>@<database URL>/'
128+
```
129+
130+
In Atlas, you can find your connection string by navigating to the `Database`
131+
option underneath `Deployment`, then select `Connect`, click `Drivers`, then
132+
select the `C++` driver. Remember to fill in the `<password>` parameter with
133+
your actual password.
134+
135+
For further help in constructing a connection string, see the MongoDB
136+
documentation
137+
[here](https://www.mongodb.com/docs/manual/reference/connection-string/).
138+
139+
Now that we have constructed the connection string, run the command below with
140+
said connection string.
141+
```sh
142+
docker run --env MONGO_CONNECTION_STRING='<your connection string here>' --rm mongocxx-ping
143+
```
144+
145+
After running the previous line, you should see this output below:
146+
```
147+
Pinged your deployment using the MongoDB C++ Driver. You successfully connected to MongoDB!
148+
```
149+
150+
## C Driver Example Usage (mongo-c-driver)
151+
152+
Because the C++ driver is a wrapper around the C driver, this image also
153+
includes the MongoDB C driver.
154+
155+
First, get access to a MongoDB database server. The easiest way to do this is by
156+
using [Atlas](https://www.mongodb.com/atlas/database), where you can run an `M0`
157+
instance for
158+
[free](https://www.mongodb.com/developer/products/atlas/free-atlas-cluster/).
159+
160+
Next, create a `Dockerfile` like so.
161+
```Dockerfile
162+
# Dockerfile
163+
FROM mongodb/mongo-cxx-driver:3.8.1-redhat-ubi-9.2
164+
165+
WORKDIR /build
166+
167+
RUN microdnf upgrade -y && microdnf install -y gcc
168+
169+
COPY ping.c /build/
170+
171+
RUN gcc \
172+
-o ping \
173+
ping.c \
174+
-I/usr/local/include/libmongoc-1.0/ \
175+
-I/usr/local/include/libbson-1.0 \
176+
-L/usr/local/lib64/ \
177+
-lmongoc-1.0 \
178+
-lbson-1.0
179+
180+
CMD /build/ping
181+
```
182+
183+
Now let's create a simple program to ping the server. Let's name this program
184+
`ping.c`. Notice that the connection string is stored as an environment variable
185+
and is retrieved at runtime.
186+
```C
187+
/* ping.c */
188+
#include <mongoc/mongoc.h>
189+
190+
int main(void) {
191+
mongoc_client_t *client = NULL;
192+
bson_error_t error = {0};
193+
mongoc_server_api_t *api = NULL;
194+
mongoc_database_t *database = NULL;
195+
bson_t *command = NULL;
196+
bson_t reply = BSON_INITIALIZER;
197+
int rc = 0;
198+
bool ok = true;
199+
200+
/* Initialize the MongoDB C Driver. */
201+
mongoc_init();
202+
203+
const char *connection_string = getenv("MONGO_CONNECTION_STRING");
204+
if (!connection_string) {
205+
fprintf(
206+
stderr,
207+
"environment variable 'MONGO_CONNECTION_STRING' is missing\n"
208+
);
209+
rc = 1;
210+
goto cleanup;
211+
}
212+
213+
client = mongoc_client_new(connection_string);
214+
if (!client) {
215+
fprintf(stderr, "failed to create a MongoDB client\n");
216+
rc = 1;
217+
goto cleanup;
218+
}
219+
220+
/* Set the version of the Stable API on the client. */
221+
api = mongoc_server_api_new(MONGOC_SERVER_API_V1);
222+
if (!api) {
223+
fprintf(stderr, "failed to create a MongoDB server API\n");
224+
rc = 1;
225+
goto cleanup;
226+
}
227+
228+
ok = mongoc_client_set_server_api(client, api, &error);
229+
if (!ok) {
230+
fprintf(stderr, "error: %s\n", error.message);
231+
rc = 1;
232+
goto cleanup;
233+
}
234+
235+
/* Get a handle on the "admin" database. */
236+
database = mongoc_client_get_database(client, "admin");
237+
if (!database) {
238+
fprintf(stderr, "failed to get a MongoDB database handle\n");
239+
rc = 1;
240+
goto cleanup;
241+
}
242+
243+
/* Ping the database. */
244+
command = BCON_NEW("ping", BCON_INT32(1));
245+
ok = mongoc_database_command_simple(
246+
database, command, NULL, &reply, &error
247+
);
248+
if (!ok) {
249+
fprintf(stderr, "error: %s\n", error.message);
250+
rc = 1;
251+
goto cleanup;
252+
}
253+
bson_destroy(&reply);
254+
255+
printf(
256+
"Pinged your deployment using the MongoDB C Driver. "
257+
"You successfully connected to MongoDB!\n"
258+
);
259+
260+
cleanup:
261+
bson_destroy(command);
262+
mongoc_database_destroy(database);
263+
mongoc_server_api_destroy(api);
264+
mongoc_client_destroy(client);
265+
mongoc_cleanup();
266+
267+
return rc;
268+
}
269+
```
270+
271+
Make sure that both `Dockerfile` and `ping.c` are in the same directory as each
272+
other. For example, see the directory structure below:
273+
```
274+
$ tree .
275+
.
276+
├── Dockerfile
277+
└── ping.c
278+
```
279+
280+
Now we need to build the Docker image. Let's name this image `mongoc-ping`
281+
```sh
282+
docker build . -t mongoc-ping
283+
```
284+
285+
We need to set the environment variable that contains the connection string for
286+
our database. For an Atlas cluster, you can construct the connection string like
287+
so:
288+
```
289+
'mongodb+srv://<your username here>:<your password here>@<database URL>/'
290+
```
291+
292+
In Atlas, you can find your connection string by navigating to the `Database`
293+
option underneath `Deployment`, then select `Connect`, click `Drivers`, then
294+
select the `C` driver. Remember to fill in the `<password>` parameter with your
295+
actual password.
296+
297+
For further help in constructing a connection string, see the MongoDB
298+
documentation
299+
[here](https://www.mongodb.com/docs/manual/reference/connection-string/).
300+
301+
Now that we have constructed the connection string, run the command below with
302+
said connection string.
303+
```sh
304+
docker run --env MONGO_CONNECTION_STRING='<your connection string here>' --rm mongoc-ping
305+
```
306+
307+
After running the previous line, you should see this output below:
308+
```
309+
Pinged your deployment using the MongoDB C Driver. You successfully connected to MongoDB!
310+
```
311+
312+
# Further Reading
313+
314+
- [Documentation](https://www.mongodb.com/docs/drivers/cxx/) for mongo-cxx-driver
315+
- [Documentation](https://www.mongodb.com/docs/drivers/c/) for mongo-c-driver
316+
317+
# License
318+
319+
[Apache License Version 2.0](https://github.com/mongodb/mongo-cxx-driver/blob/master/LICENSE)

0 commit comments

Comments
 (0)