chore: make the development environment work from a clean checkout

Setting up to work on Indiekit needed steps that were either undocumented or
documented incorrectly, and the test suite depended on ambient state.

`npm test` now needs nothing at all. It already started its own in-memory
MongoDB for most tests, but `util/test/unit/mongodb.js` connected to
`mongodb://foo:bar@localhost` — port 27017 — and asserted the error was
`Authentication failed.`. That only holds when something happens to be
listening there. `docs/development.md` tells contributors to run MongoDB on
27018, so following the documented setup exactly produced a failure after a
30-second server-selection timeout. It now starts an in-memory server with
authentication enabled, which is deterministic, needs no service, and takes
180ms rather than 30s.

The test scripts also supply development defaults for SECRET and
PASSWORD_SECRET, overridden by real environment variables when set. Without
them the suite reports 115 failures that look like broken code rather than a
missing environment. CI passes both from repository secrets, which are not
available to pull requests from forks.

`compose.yml` replaces the block of YAML that development.md asked
contributors to copy by hand. That copy pinned mongo:7.0.11 — a release the
README warns against, being affected by CVE-2025-14847 — and required
`docker volume create` first, because it declared the volume external.

Also adds `.env.example`, and corrects `npm run dev --production`, which
passes the flag to npm rather than to the script.

Author: rmdes

.env.example

@@ -0,0 +1,30 @@
+# Copy to `.env` and edit. Nothing here is needed to run `npm test`.
+
+PUBLICATION_URL="http://localhost:3000"
+
+# Used by @indiekit/endpoint-auth to sign and verify tokens, and to salt the
+# password. Any non-empty value works locally.
+SECRET="development"
+
+# Hashed and salted password used when signing in. Generate by starting the
+# server and visiting /auth/new-password.
+PASSWORD_SECRET=""
+
+# MongoDB. These match the defaults in compose.yml — `npm run db:up` reads
+# them, so changing the credentials here changes them in the container too.
+# MongoDB is optional; leave MONGO_URL unset to run without persistence.
+MONGO_PORT="27018"
+MONGO_INITDB_ROOT_USERNAME="indiekit"
+MONGO_INITDB_ROOT_PASSWORD="indiekit"
+MONGO_URL="mongodb://indiekit:indiekit@localhost:27018"
+
+# Content store — see docs/development.md for the alternatives.
+# GITHUB_USER=""
+# GITHUB_REPO=""
+# GITHUB_BRANCH="main"
+# GITHUB_TOKEN=""
+
+# Syndicators — see docs/development.md.
+# MASTODON_URL=""
+# MASTODON_USER=""
+# MASTODON_ACCESS_TOKEN=""

.prettierignore

@@ -4,3 +4,4 @@ docs/**/*.md
 **/locales/*.json
 *.html
 CHANGELOG.md
+*.env.example

compose.yml

@@ -0,0 +1,34 @@
+# Development MongoDB for working on Indiekit itself.
+#
+#   npm run db:up      start it
+#   npm run db:down    stop it, keeping the data
+#   npm run db:reset   stop it and discard the data
+#
+# The test suite does not need this — `npm test` starts its own in-memory
+# MongoDB and requires no running services. This is here so that `npm start`
+# and `npm run dev` have a database to talk to.
+#
+# The port defaults to 27018 rather than 27017 so it does not collide with a
+# MongoDB already installed on the host. Override it with MONGO_PORT.
+
+services:
+  mongo:
+    image: mongo:8
+    container_name: indiekit-dev-mongo
+    restart: unless-stopped
+    ports:
+      - "${MONGO_PORT:-27018}:27017"
+    volumes:
+      - mongo-data:/data/db
+    environment:
+      - MONGO_INITDB_ROOT_USERNAME=${MONGO_INITDB_ROOT_USERNAME:-indiekit}
+      - MONGO_INITDB_ROOT_PASSWORD=${MONGO_INITDB_ROOT_PASSWORD:-indiekit}
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping')"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 20s
+
+volumes:
+  mongo-data:

docs/development.md

@@ -1,6 +1,8 @@
 # Setting up a local development environment
 
-To begin local development on the Indiekit project, clone this repository, configure a [content store](concepts#content-store), [publication preset](concepts#publication-preset) and [syndicator](concepts#syndication), and create a MongoDB database you can connect to.
+To begin local development on the Indiekit project, clone this repository, run `npm install`, then copy `.env.example` to `.env`. To run the server you will also want a [content store](concepts#content-store), [publication preset](concepts#publication-preset) and [syndicator](concepts#syndication), and a MongoDB database to connect to.
+
+Running the tests needs none of that — see [Tests](#tests).
 
 ## Project structure
 
@@ -32,42 +34,26 @@ Express waits for a resolved configuration file before starting the server.
 
 ## MongoDB
 
-Indiekit uses a MongoDB database for persistence. A convenient way to run MongoDB locally is to use [Docker Compose](https://docs.docker.com/compose/). Since the filesystem of a Docker container is ephemeral, you will need to create a [Docker volume](https://docs.docker.com/storage/volumes/). You can do this with the following docker command:
+Indiekit uses a MongoDB database for persistence. The repository ships a
+`compose.yml` that runs one, so you do not need to install MongoDB locally:
 
 ```sh
-docker volume create mongo-data
+npm run db:up
 ```
 
-Create a `docker-compose.yml` file that runs a service on an available port of your Docker host (e.g. 27018) and uses the Docker volume you have just created.
-
-```yml
-version: '3.9'
-services:
-  mongo:
-    container_name: mongo
-    environment:
-      - MONGO_INITDB_ROOT_USERNAME
-      - MONGO_INITDB_ROOT_PASSWORD
-    image: mongo:7.0.11
-    network_mode: bridge
-    ports:
-    - '27018:27017'
-    restart: always
-    volumes:
-      - mongo-data:/data/db
-volumes:
-  mongo-data:
-    external: true
-```
+This starts MongoDB on port 27018 of your host, storing its data in a named
+Docker volume so it survives a restart. Use `npm run db:down` to stop it, or
+`npm run db:reset` to stop it and discard the data.
 
-This configuration tells Docker to run the `mongo` service on port 27017 of the `mongo` container, and expose port 27018 on the Docker host (e.g. your computer).
+The port defaults to 27018 rather than 27017 so that it does not collide with
+a MongoDB already installed on your machine. Set `MONGO_PORT` to change it.
 
-You can set the necessary environment variables in a `.env` file:
+Copy `.env.example` to `.env` to get a matching `MONGO_URL`:
 
 ```dotenv
-MONGO_INITDB_ROOT_USERNAME="username"
-MONGO_INITDB_ROOT_PASSWORD="password"
-MONGO_URL="mongodb://$MONGO_INITDB_ROOT_USERNAME:$MONGO_INITDB_ROOT_PASSWORD@localhost:27018"
+MONGO_INITDB_ROOT_USERNAME="indiekit"
+MONGO_INITDB_ROOT_PASSWORD="indiekit"
+MONGO_URL="mongodb://indiekit:indiekit@localhost:27018"
 ```
 
 > [!TIP]
@@ -76,6 +62,9 @@ MONGO_URL="mongodb://$MONGO_INITDB_ROOT_USERNAME:$MONGO_INITDB_ROOT_PASSWORD@loc
 > [!TIP]
 > To inspect data stored in a MongoDB database, use the [MongoDB shell](https://www.mongodb.com/products/tools/shell) or an application like [Compass](https://www.mongodb.com/products/tools/compass).
 
+> [!NOTE]
+> MongoDB is optional. Leave `MONGO_URL` unset to run Indiekit without persistence; see the [README](https://github.com/getindiekit/indiekit#readme) for which features need a database.
+
 ## Configure a content store
 
 Indiekit performs create, read, update and delete (CRUD) operations on files that are stored in a content store. Different content stores require different configurations and credentials.
@@ -171,6 +160,12 @@ The project uses both unit and integration tests. Run tests using the following
 npm test
 ```
 
+The test suite needs no setup at all: it starts its own in-memory MongoDB, so
+no database has to be running, and the `test` script supplies development
+defaults for `NODE_ENV`, `SECRET` and `PASSWORD_SECRET`. A clean checkout can
+run `npm install && npm test` straight away. Setting `SECRET` or
+`PASSWORD_SECRET` in the environment overrides the default.
+
 To run a single test suite, use `node` followed by the path to the test. For example:
 
 ```sh

package.json

@@ -29,6 +29,9 @@
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "dev": "node --watch-path=./ packages/indiekit/bin/cli.js serve",
+    "db:up": "docker compose up --detach --wait",
+    "db:down": "docker compose down",
+    "db:reset": "docker compose down --volumes",
     "debug": "indiekit serve --debug",
     "start": "indiekit serve",
     "lint:prettier": "prettier . --check",
@@ -39,9 +42,9 @@
     "lint:css:fix": "stylelint '**/*.css' --fix",
     "lint": "npm run lint:prettier && npm run lint:js && npm run lint:css",
     "lint:fix": "npm run lint:prettier:fix && npm run lint:js:fix && npm run lint:css:fix",
-    "test": "NODE_ENV=test node --test --test-reporter=spec",
-    "test:coverage": "NODE_ENV=test node --test --experimental-test-coverage",
-    "test:lcov": "NODE_ENV=test node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info"
+    "test": "NODE_ENV=test SECRET=${SECRET:-test} PASSWORD_SECRET=${PASSWORD_SECRET:-test} node --test --test-reporter=spec",
+    "test:coverage": "NODE_ENV=test SECRET=${SECRET:-test} PASSWORD_SECRET=${PASSWORD_SECRET:-test} node --test --experimental-test-coverage",
+    "test:lcov": "NODE_ENV=test SECRET=${SECRET:-test} PASSWORD_SECRET=${PASSWORD_SECRET:-test} node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info"
   },
   "workspaces": [
     "helpers/*",

packages/util/test/unit/mongodb.js

@@ -74,12 +74,27 @@ describe("util/lib/mongodb", async () => {
     );
   });
 
+  // Uses an in-memory server with authentication enabled rather than whatever
+  // happens to be listening on port 27017. The suite must not depend on a
+  // service it did not start: `docs/development.md` puts MongoDB on 27018, so
+  // a correctly configured machine would otherwise fail here after a
+  // 30-second server-selection timeout.
   it("Returns error if can’t connect to MongoDB client", async () => {
+    const authServer = await MongoMemoryServer.create({
+      auth: { enable: true },
+    });
     mock.method(console, "error", () => {});
 
-    await getMongodbClient("mongodb://foo:bar@localhost");
-    const result = console.error.mock.calls[0].arguments[0];
-
-    assert.equal(result, `Authentication failed.`);
+    try {
+      const uri = authServer
+        .getUri()
+        .replace("mongodb://", "mongodb://foo:bar@");
+      await getMongodbClient(uri);
+      const result = console.error.mock.calls[0].arguments[0];
+
+      assert.equal(result, `Authentication failed.`);
+    } finally {
+      await authServer.stop();
+    }
   });
 });