add a tool for automatically configuring MongoDB, and update Quickstart guide

Author: tayloraswift

Guides/docs.docc/Quickstart.md

@@ -41,42 +41,26 @@ Unidoc is an ordinary SwiftPM executable product. You can build it for your macO
 
 @Code(file: unidoc-from-source.sh, title: unidoc-from-source.sh)
 
-Please note that the executable as built by SwiftPM is named `unidoc-tools`, which you should rename to `unidoc` when installing it.
-
 
 >   Important:
 >   The rest of this guide assumes you have installed Unidoc somewhere on your macOS host that is visible in your `PATH` and allows you to invoke it as `unidoc`.
 
 
 ## 3. Launching a `mongod` instance
 
-If you have not already done so, clone the Unidoc project and navigate to the root of the repository:
+Unidoc can configure a `mongod` instance for you through the `unidoc init` command. This tool takes a directory path as an argument, which it uses to persist the state of the database. In the example below, we will create the documentation database in a directory named `unidoc` in your home directory.
 
 ```bash
-git clone https://github.com/tayloraswift/swift-unidoc
-cd swift-unidoc
+unidoc init ~/unidoc
 ```
 
-Use Docker Compose to launch a `mongod` instance in a container. This container is named `unidoc-mongod-container`. It has persistent state which `mongod` stores in a directory called `.mongod` at the root of the repository.
-
-```bash
-docker compose -f Guides/docs.docc/local/docker-compose.yml up
-```
+Please note that this will start a Docker container that runs continuously in the background. Therefore, if you want to dismantle the database, you must stop the container before deleting the persistence directory, otherwise it may recreate some of the files you delete.
 
 @Image(source: "Docker Desktop.png", alt: "Docker Desktop") {
 >   You should see the `unidoc-mongod-container` running in the Docker Desktop GUI.
 }
 
 
-The container is home to a MongoDB [replica set](https://www.mongodb.com/docs/manual/reference/replica-configuration/) which you need to initialize.
-
-Open a new terminal and run the following command to initialize the replica set:
-
-```bash
-docker exec -t unidoc-mongod-container /bin/mongosh --file /unidoc-rs-init.js
-```
-
-
 ## 3. Running `unidoc preview`
 
 The `unidoc preview` tool is a simple web server that links and serves documentation for local Swift packages. Run it directly from your macOS host like this:

Guides/docs.docc/local/load-standard-library.sh

@@ -1 +1 @@
-swift run -c release unidoc-tools local swift
+swift run -c release unidoc local swift

Guides/docs.docc/local/load-swift-nio.sh

@@ -1 +1 @@
-swift run -c release unidoc-tools local swift-nio -I /swift
+swift run -c release unidoc local swift-nio -I /swift

Guides/docs.docc/local/start-server.sh

@@ -1,2 +1,2 @@
 swift --version
-swift run -c release unidoc-tools preview
+swift run -c release unidoc preview

Guides/docs.docc/local/unidoc-from-source.sh

@@ -1,5 +1,5 @@
 mkdir -p ~/unidoc/bin
 git clone https://github.com/tayloraswift/swift-unidoc
 cd swift-unidoc
-swift build -c release --product unidoc-tools
-mv .build/release/unidoc-tools ~/unidoc/bin/unidoc
+swift build -c release --product unidoc
+mv .build/release/unidoc ~/unidoc/bin/unidoc

Sources/unidoc-tools/Main.Init.Installation.swift

@@ -0,0 +1,108 @@
+import System
+
+extension Main.Init
+{
+    struct Installation
+    {
+        let docker_compose_yml:FilePath
+        let unidoc_rs_init_js:FilePath
+        let unidoc_rs_conf:FilePath
+
+        let container:String
+        let localhost:Bool
+    }
+}
+extension Main.Init.Installation
+{
+    func create() throws
+    {
+        for (file, content):(FilePath, String) in [
+            (
+                self.docker_compose_yml,
+                Self.docker_compose_yml(container: self.container)
+            ),
+            (
+                self.unidoc_rs_conf,
+                Self.unidoc_rs_conf
+            ),
+            (
+                self.unidoc_rs_init_js,
+                Self.unidoc_rs_init_js(host: self.localhost ? "localhost" : "unidoc-mongod")
+            )
+        ]
+        {
+            try file.open(.writeOnly, permissions: (.rw, .r, .r), options: [.create, .truncate])
+            {
+                _ = try $0.writeAll(content.utf8)
+            }
+        }
+    }
+}
+
+extension Main.Init.Installation
+{
+    private
+    static func docker_compose_yml(container:String) -> String
+    {
+        """
+        services:
+            unidoc-mongod:
+                image: mongo:latest
+                container_name: \(container)
+                hostname: unidoc-mongod
+                networks:
+                    - unidoc-test
+                ports:
+                    - 27017:27017
+                restart: always
+                volumes:
+                    # cannot put this in docker-entrypoint-initdb.d, it does not work
+                    - ./unidoc-rs-init.js:/unidoc-rs-init.js
+                    - ./unidoc-rs.conf:/etc/mongod.conf
+                    - ./mongod:/data/db
+                command: mongod --config /etc/mongod.conf
+
+
+        networks:
+            unidoc-test:
+                name: unidoc-test
+                enable_ipv6: true
+                ipam:
+                    config:
+                        - subnet: 2001:0DB8::/112
+
+        """
+    }
+
+    private
+    static let unidoc_rs_conf:String = """
+    replication:
+        replSetName: unidoc-rs
+    net:
+        port: 27017
+        bindIp: 0.0.0.0
+        bindIpAll: true
+
+    """
+
+    private
+    static func unidoc_rs_init_js(host:String) -> String
+    {
+        """
+        db = connect('mongodb://unidoc-mongod:27017/admin');
+        db.runCommand({'replSetInitiate': {
+            "_id": "unidoc-rs",
+            "version": 1,
+            "members": [
+                {
+                    "_id": 0,
+                    "host": "\(host):27017",
+                    "tags": {},
+                    "priority": 1
+                }
+            ]
+        }});
+
+        """
+    }
+}

Sources/unidoc-tools/Main.Init.swift

@@ -0,0 +1,99 @@
+import ArgumentParser
+import System
+
+extension Main
+{
+    struct Init
+    {
+        @Argument
+        var location:FilePath.Directory
+
+        @Option(
+            name: [.customLong("container"), .customShort("c")],
+            help: "Container name")
+        var container:String = "unidoc-mongod-container"
+
+        @Flag(
+            name: [.customLong("containerized"), .customShort("m")],
+            help: """
+            Use containerized setup - this prevents documentation preview servers from running \
+            on the host, but allows preview servers to run from inside other Docker containers
+            """)
+        var containerized:Bool = false
+    }
+}
+extension Main.Init:AsyncParsableCommand
+{
+    public
+    static let configuration:CommandConfiguration = .init(commandName: "init")
+
+    func run() async throws
+    {
+        try self.location.create()
+
+        let installation:Installation = .init(
+            docker_compose_yml: self.location / "docker-compose.yml",
+            unidoc_rs_init_js: self.location / "unidoc-rs-init.js",
+            unidoc_rs_conf: self.location / "unidoc-rs.conf",
+            container: self.container,
+            localhost: !self.containerized)
+
+        try installation.create()
+
+        try SystemProcess.init(command: "docker",
+            "compose",
+            "--file", "\(installation.docker_compose_yml)",
+            "up",
+            "--detach",
+            "--wait",
+            echo: true)()
+
+        //  Even though the container is ready, the `mongod` daemon within it may not be.
+        //  We need to wait for it to be ready before we can run the `mongosh` command.
+        //  We do this by pinging the `mongod` daemon until it responds.
+        print("Waiting for mongod to start up...")
+
+        var attempts:Int = 0
+        waiting: do
+        {
+            async
+            let interval:Void = Task.sleep(for: .seconds(1))
+            do
+            {
+                try SystemProcess.init(command: "docker",
+                    "exec",
+                    "\(installation.container)",
+                    "mongosh",
+                    "--quiet",
+                    "--eval", "exit")()
+            }
+            catch let error
+            {
+                if  attempts > 10
+                {
+                    throw error
+                }
+                else
+                {
+                    attempts += 1
+                }
+
+                try await interval
+                continue waiting
+            }
+        }
+
+        print("Initializing replica set...")
+
+        try SystemProcess.init(command: "docker",
+            "exec",
+            "--tty",
+            "\(installation.container)",
+            "/bin/mongosh", "--file", "/unidoc-rs-init.js",
+            echo: true)()
+
+        print("Successfully initialized MongoDB replica set!")
+        print("    Docker compose file: \(installation.docker_compose_yml)")
+        print("    Docker container: \(installation.container)")
+    }
+}

Sources/unidoc-tools/Main.swift

@@ -6,6 +6,7 @@ struct Main:AsyncParsableCommand
 {
     static let configuration:CommandConfiguration = .init(subcommands: [
             SSGC.Compile.self,
+            Init.self,
             Local.self,
             Preview.self
         ])