feat(*): start mongo-express on demand, constraint v1.24.4, update readme (#22)

* feat: start mongo-express on demand, update readme, constraint v1.24.4

* whitelist latest release link

* Small README.md changes

* test: add `sleep 3`

* Remove sleep in mongo-express entrypoint (we already have a delayed start)

* And we don't need to override mongo-express entrypoint in this case

* Add `condition: service_healthy`

* Say "on demand" for Mongo Express

Author: stasadev

.github/workflows/doc-links.yml

@@ -22,7 +22,7 @@ jobs:
         with:
           path: sources
 
-      - name: Lauch localhost server
+      - name: Launch localhost server
         run: |
           sudo npm install --global http-server
           http-server ./sources &
@@ -36,4 +36,4 @@ jobs:
         run: |
           gem install awesome_bot
           cd sources
-          awesome_bot README.md --skip-save-results --allow-dupe --base-url http://localhost:8080/ --white-list ddev.site
+          awesome_bot README.md --skip-save-results --allow-dupe --base-url http://localhost:8080/ --white-list ddev.site,github.com/ddev/ddev-mongo/releases/latest

README.md

@@ -1,61 +1,91 @@
-[![tests](https://github.com/ddev/ddev-mongo/actions/workflows/tests.yml/badge.svg)](https://github.com/ddev/ddev-mongo/actions/workflows/tests.yml) ![project is maintained](https://img.shields.io/maintenance/yes/2024.svg)
+[![add-on registry](https://img.shields.io/badge/DDEV-Add--on_Registry-blue)](https://addons.ddev.com)
+[![tests](https://github.com/ddev/ddev-mongo/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/ddev/ddev-mongo/actions/workflows/tests.yml?query=branch%3Amain)
+[![last commit](https://img.shields.io/github/last-commit/ddev/ddev-mongo)](https://github.com/ddev/ddev-mongo/commits)
+[![release](https://img.shields.io/github/v/release/ddev/ddev-mongo)](https://github.com/ddev/ddev-mongo/releases/latest)
 
-## What is ddev-mongo?
+# DDEV Mongo
 
-This repository is an add-on that provides Mongo and Mongo Express for [DDEV](https://ddev.readthedocs.io/en/stable/).
+## Overview
 
-It's based on [MongoDb from Docker Hub](https://hub.docker.com/_/mongo?tab=description#-via-docker-stack-deploy-or-docker-compose), [DDEV custom compose files](https://ddev.readthedocs.io/en/stable/users/extend/custom-compose-files/) and [API Platform tutorial](https://api-platform.com/docs/core/mongodb/#enabling-mongodb-support).
+[MongoDB](https://www.mongodb.com/) is a source-available, cross-platform, document-oriented database program. Classified as a NoSQL database product, MongoDB uses JSON-like documents with optional schemas.
 
-## Installation
-
-For DDEV v1.23.5 or above run
-
-```bash
-ddev add-on get ddev/ddev-mongo
-```
+This add-on integrates MongoDB and Mongo Express into your [DDEV](https://ddev.com/) project.
 
-For earlier versions of DDEV run
+It's based on [MongoDB from Docker Hub](https://hub.docker.com/_/mongo?tab=description), [DDEV custom compose files](https://ddev.readthedocs.io/en/stable/users/extend/custom-compose-files/) and [API Platform tutorial](https://api-platform.com/docs/core/mongodb/#enabling-mongodb-support).
 
-```bash
-ddev get ddev/ddev-mongo
-```
-
-Then restart your project
+## Installation
 
 ```bash
+ddev add-on get ddev/ddev-mongo
 ddev restart
 ```
 
+After installation, make sure to commit the `.ddev` directory to version control.
+
 ## Configuration
 
 1. Your project will likely require the [Doctrine MongoDB ODM bundle](https://github.com/doctrine/DoctrineMongoDBBundle)
    `ddev composer require doctrine/mongodb-odm-bundle:^4.0.0@beta doctrine/mongodb-odm:^2.0.0@beta`
 
 2. In your application `.env` or other client, set the connection string:
 
-   ```
+   ```dotenv
    MONGODB_URL=mongodb://db:db@mongo:27017
    ```
 
-Mongo Express will now be accessible by running `ddev mongo-express` command.
-
-## Features
-
-### `ddev mongosh` command
+Mongo Express can now be started on demand using the `ddev mongo-express` command. (This optional feature is available starting from DDEV v1.24.4+.)
 
-This command will run the `mongosh` (mongoDB Shell) command in the `mongo` container. Please [read the documentation](https://www.mongodb.com/docs/mongodb-shell/) for more information.
+## Usage
 
-### `ddev mongo-express` command
-
-This command opens your browser to the Mongo Express page.
+| Command | Description |
+| ------- | ----------- |
+| `ddev mongosh` | Run MongoDB Shell, see the [documentation](https://www.mongodb.com/docs/mongodb-shell/) |
+| `ddev mongo-express` | Start web-based MongoDB admin interface |
+| `ddev describe` | View service status and used ports for MongoDB |
+| `ddev logs -s mongo` | Check MongoDB logs |
+| `ddev logs -s mongo-express` | Check Mongo Express logs (if it's started) |
 
 ## Caveats:
 
-- The php extension (phpX.X-mongodb) is set up in `.ddev/config.mongo.yaml` using `webimage_extra_packages`. You may want to edit your config.yaml to do what you want and remove the config.mongo.yaml.
+- The php extension (`phpX.X-mongodb`) is set up in `.ddev/config.mongo.yaml` using `webimage_extra_packages`. You may want to edit your `.ddev/config.yaml` to do what you want and remove the `.ddev/config.mongo.yaml`.
 - You can't define custom MongoDB configuration with this current setup.
 - You can't use `ddev import-db` to import to mongo.
 
-**Based on the original [ddev-contrib recipe](https://github.com/ddev/ddev-contrib/tree/master/docker-compose-services/mongodb)**
+## Advanced Customization
+
+If you don't want to authenticate with the default admin user, create a new file `.ddev/docker-compose.mongo_extra.yaml`:
+
+```yaml
+services:
+  mongo:
+    environment:
+      - MONGO_INITDB_ROOT_USERNAME=
+      - MONGO_INITDB_ROOT_PASSWORD=
+  mongo-express:
+    environment:
+      - ME_CONFIG_MONGODB_URL=mongodb://mongo:27017
+```
+
+(Don't forget to update your application's `.env` file.)
+
+To change the Docker image:
+
+```bash
+ddev dotenv set .ddev/.env.mongo --mongo-docker-image=mongo:5-focal
+ddev add-on get ddev/ddev-mongo
+ddev restart
+```
+
+Make sure to commit the `.ddev/.env.mongo` file to version control.
+
+All customization options (use with caution):
+
+| Variable | Flag | Default |
+| -------- | ---- | ------- |
+| `MONGO_DOCKER_IMAGE` | `--mongo-docker-image` | `mongo:5-focal` |
+| `MONGO_EXPRESS_DOCKER_IMAGE` | `--mongo-express-docker-image` | `mongo-express:1.0` |
+
+## Credits
 
 **Originally contributed by [@wtfred](https://github.com/wtfred)**
 

commands/host/mongo-express

@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 
 ## #ddev-generated: If you want to edit and own this file, remove this line.
 ## Description: Launch a browser with Mongo Express
@@ -11,6 +11,9 @@ if [ "${DDEV_PRIMARY_URL%://*}" != "http" ] && [ -z "${GITPOD_WORKSPACE_ID:-}" ]
     PROTOCOL="HTTPS"
 fi
 
+# Start mongo-express if it's not started
+ddev exec -s mongo-express true >/dev/null 2>&1 || ddev start --profiles mongo-express
+
 # Fetch the appropriate port within the mongo-express container
 DDEV_MONGO_EXPRESS_PORT=$(ddev exec -s mongo-express sh -c "printenv | grep -w ${PROTOCOL}_EXPOSE | cut -d '=' -f 2 | cut -d ':' -f 1")
 
@@ -20,4 +23,3 @@ if [ -z "$DDEV_MONGO_EXPRESS_PORT" ]; then
 fi
 
 ddev launch :"$DDEV_MONGO_EXPRESS_PORT"
-

commands/mongo/mongosh

@@ -1,11 +1,11 @@
-#!/bin/bash
+#!/usr/bin/env bash
 #ddev-generated
 # Remove the line above if you don't want this file to be overwritten when you run
 # ddev get ddev/ddev-mongo
 #
 # This file comes from https://github.com/ddev/ddev-mongo
 #
-## Description: Run mongosh command
+## Description: Run MongoDB Shell command
 ## Usage: mongosh <command>
 ## ExecRaw: true
 ## Example: "ddev mongosh "mongodb://mongo:27017"

docker-compose.mongo.yaml

@@ -1,60 +1,57 @@
 #ddev-generated
-# Remove the line above if you don't want this file to be overwritten when you run
-# ddev get ddev/ddev-mongo
-#
-# This file comes from https://github.com/ddev/ddev-mongo
-#
 services:
   mongo:
     container_name: ddev-${DDEV_SITENAME}-mongo
-    image: mongo:5-focal
+    image: ${MONGO_DOCKER_IMAGE:-mongo:5-focal}
     volumes:
-    - type: "volume"
-      source: mongo
-      target: "/data/db"
-      volume:
-        nocopy: true
-    - type: "volume"
-      source: mongo-config
-      target: "/data/configdb"
-      volume:
-        nocopy: true
-    - ".:/mnt/ddev_config"
+      - type: "volume"
+        source: mongo
+        target: "/data/db"
+        volume:
+          nocopy: true
+      - type: "volume"
+        source: mongo-config
+        target: "/data/configdb"
+        volume:
+          nocopy: true
+      - ".:/mnt/ddev_config"
+      - "ddev-global-cache:/mnt/ddev-global-cache"
     restart: "no"
     expose:
-    - "27017"
+      - "27017"
     labels:
       com.ddev.site-name: ${DDEV_SITENAME}
-      com.ddev.approot: $DDEV_APPROOT
+      com.ddev.approot: ${DDEV_APPROOT}
     environment:
-    - MONGO_INITDB_ROOT_USERNAME=db
-    - MONGO_INITDB_ROOT_PASSWORD=db
-    # See https://github.com/docker-library/docs/tree/master/mongo#mongo_initdb_database
-    # - MONGO_INITDB_DATABASE=db
+      - MONGO_INITDB_ROOT_USERNAME=db
+      - MONGO_INITDB_ROOT_PASSWORD=db
+      # See https://github.com/docker-library/docs/tree/master/mongo#mongo_initdb_database
+      # - MONGO_INITDB_DATABASE=db
     healthcheck:
       test: ["CMD-SHELL", "mongo --eval 'db.runCommand(\"ping\").ok' localhost:27017/test --quiet"]
       timeout: 60s
 
   mongo-express:
     container_name: ddev-${DDEV_SITENAME}-mongo-express
-    image: mongo-express:1.0
+    image: ${MONGO_EXPRESS_DOCKER_IMAGE:-mongo-express:1.0}
     restart: "no"
     labels:
       com.ddev.site-name: ${DDEV_SITENAME}
       com.ddev.approot: ${DDEV_APPROOT}
-      com.ddev.platform: ddev
     expose:
-    - "8081"
+      - "8081"
     environment:
-      VIRTUAL_HOST: $DDEV_HOSTNAME
-      ME_CONFIG_MONGODB_ENABLE_ADMIN: "true"
-      ME_CONFIG_BASICAUTH: "false"
-      ME_CONFIG_MONGODB_URL: "mongodb://db:db@mongo:27017"
-      HTTP_EXPOSE: "9091:8081"
-      HTTPS_EXPOSE: "9092:8081"
+      - ME_CONFIG_MONGODB_ENABLE_ADMIN=true
+      - ME_CONFIG_BASICAUTH=false
+      - ME_CONFIG_MONGODB_URL=mongodb://db:db@mongo:27017
+      - VIRTUAL_HOST=$DDEV_HOSTNAME
+      - HTTP_EXPOSE=9091:8081
+      - HTTPS_EXPOSE=9092:8081
     depends_on:
-      - mongo
-    entrypoint: [sh, -c, "sleep 5s && tini -- /docker-entrypoint.sh mongo-express"]
+      mongo:
+        condition: service_healthy
+    profiles:
+      - mongo-express
 
 volumes:
   mongo:

install.yaml

@@ -4,15 +4,8 @@ pre_install_actions:
   - |
     #ddev-description:Create config.mongo.yaml with webimage_extra_packages in it
     printf '#ddev-generated\nwebimage_extra_packages: ["php${DDEV_PHP_VERSION}-mongodb"]\n' >.ddev/config.mongo.yaml
-  # Ensure we're on DDEV 1.23+. It's required for the `mongo-express` command (launch by port).
-  # ddev_version_constraint (see below) is only available in DDEV 1.23.4+, so we keep this check for now.
-  # Should be removed when DDEV 1.24 is released.
-  - |
-    #ddev-nodisplay
-    #ddev-description:Checking DDEV version
-    (ddev debug capabilities | grep corepack >/dev/null) || (echo "Please upgrade DDEV to v1.23+ to enable launching." && false)
 
-ddev_version_constraint: ">= v1.23.0"
+ddev_version_constraint: ">= v1.24.4"
 
 post_install_actions:
   - |
@@ -24,7 +17,6 @@ post_install_actions:
   - |
     echo "You can now use 'ddev mongo-express' to launch Mongo Express UI"
 
-# list of files and directories listed that are copied into project .ddev directory
 project_files:
   - commands/mongo/mongosh
   - commands/host/mongo-express

tests/test.bats

@@ -47,8 +47,10 @@ health_checks() {
   assert_success
   assert_output --partial '"ok":1'
 
+  # Start mongo-express profile
   DDEV_DEBUG=true run ddev mongo-express
   assert_success
+  assert_output --partial "mongo-express"
   assert_output --partial "FULLURL https://${PROJNAME}.ddev.site:9092"
 
   run curl -sfI https://${PROJNAME}.ddev.site:9092/db/admin/expArr/system.users