Replace getting started with one from Quix-Streams

Dockerfile

@@ -0,0 +1,24 @@
+FROM python:3.11-slim
+
+WORKDIR /docs
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    libcairo2-dev \
+    libgdk-pixbuf2.0-dev \
+    libpango1.0-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements and install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy the docs content
+COPY . .
+
+# Expose the port MkDocs runs on
+EXPOSE 8000
+
+# Command to run MkDocs
+CMD ["mkdocs", "serve", "--no-directory-urls", "--dev-addr=0.0.0.0:8000"] 

RUNNING-DOCS-LOCALLY.md

@@ -1,43 +1,119 @@
-# Running docs locally
+# Running Docs with Docker
 
-The following is only required if you are part of the Quix technical writing team, or you contribute frequently, and want to check your docs PR locally before pushing up to the docs repo. Otherwise, the simplest approach is to refer to the [docs preview site](./README.md#docs-preview-site) that is created automatically for you, when you push up a PR on the `dev` branch.
+This guide explains how to run the Quix documentation locally using Docker Compose. This is an alternative to the native installation method described in [RUNNING-DOCS-LOCALLY.md](./RUNNING-DOCS-LOCALLY.md).
 
 ## Prerequisites
 
-To run these docs locally you'll need:
+- [Docker](https://docs.docker.com/get-docker/) installed on your system
+- [Docker Compose](https://docs.docker.com/compose/install/) installed on your system
+- Git client (for cloning the repository)
 
-* [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)
-* Sign up to the [Insiders Programme](https://squidfunk.github.io/mkdocs-material/insiders/), if you want to see all features rendered locally.
-* A Git client (the command line is fine).
+## Quick Start
 
-## Plugins used
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/quixio/quix-docs.git
+   cd quix-docs
+   ```
+
+2. Make the browser script executable:
+   ```bash
+   chmod +x open-browser.sh
+   ```
+
+3. Start the documentation server:
+   ```bash
+   docker compose up --build & ./open-browser.sh
+   ```
+
+   Or to run in detached mode:
+   ```bash
+   docker compose up -d --build && ./open-browser.sh
+   ```
+
+4. The documentation will automatically open in your default browser at `http://localhost:8000/docs/`
 
-If you want to fully render all documentation locally you need to install the following plugins with `pip install`:
+## Service Management
 
-* [mkdocs-glightbox](https://pypi.org/project/mkdocs-glightbox/0.1.0/)
-* [mkdocs-multirepo-plugin](https://github.com/jdoiro3/mkdocs-multirepo-plugin)
-* [mkdocs-redirects](https://pypi.org/project/mkdocs-redirects/)
+- Start in detached mode (runs in background):
+  ```bash
+  docker compose up -d --build && ./open-browser.sh
+  ```
 
-You also need to sign up to the [Insiders Programme](https://squidfunk.github.io/mkdocs-material/insiders/).
+- Stop the service:
+  ```bash
+  docker compose down
+  ```
 
-The [social plugin](https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/) is also used to automatically provide metadata. See the [social plugin documentation](https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/) for details on how to install the dependencies of the plugin. You might also need to first install `cffi` with `pip install cffi`, if not present on your system.
+- View logs:
+  ```bash
+  docker compose logs -f
+  ```
 
-## Linked repositories
+- Rebuild the service:
+  ```bash
+  docker compose build
+  ```
 
-This repo uses the `multirepo` plugin to pull in client library content from the [Quix Streams repo](https://github.com/quixio/quix-streams). 
+- Force rebuild and start:
+  ```bash
+  docker compose up --build
+  ```
 
-You can read more about Quix Streams [here](https://github.com/quixio/quix-streams/blob/main/README.md).
+## Features
 
-## Viewing the docs
+- Live reload: Changes to documentation are reflected in real-time
+- Automatic restart: Service restarts automatically on failure
+- Volume mounting: Local directory is mounted for immediate updates
+- Log streaming: View logs in real-time with `docker compose logs -f`
+- Automatic browser opening: Documentation opens in your default browser
 
-To view the docs locally:
+## Troubleshooting
 
-1. Follow the install guide for Material [here](https://squidfunk.github.io/mkdocs-material/getting-started/).
-2. Clone the repo as follows:
+If you encounter issues:
 
+1. Port conflicts:
+   ```bash
+   # Check if port 8000 is in use
+   lsof -i :8000
+   # Or on Windows:
+   netstat -ano | findstr :8000
    ```
-   git clone https://github.com/quixio/quix-docs.git
+
+2. Docker resource issues:
+   ```bash
+   # Check Docker system resources
+   docker system df
+   docker system prune  # Clean up unused resources
    ```
-3. Change into the docs directory you cloned (there will be a `mkdocs.yml` file there). 
-4. Run `mkdocs serve --no-directory-urls`.
-5. Navigate your browser to `localhost:8000` to view the docs.
+
+3. Build issues:
+   ```bash
+   # Clean build with no cache
+   docker compose build --no-cache
+   # Remove all containers and images
+   docker compose down --rmi all
+   ```
+
+4. Permission issues:
+   ```bash
+   # Ensure Docker has proper permissions
+   sudo usermod -aG docker $USER
+   # Log out and back in for changes to take effect
+   ```
+
+5. Network issues:
+   ```bash
+   # Check Docker network
+   docker network ls
+   # Inspect network configuration
+   docker network inspect quix-docs_default
+   ```
+
+6. Service health:
+   ```bash
+   # Check service status
+   docker compose ps
+   # View service logs
+   docker compose logs
+   ``` 

docker-compose.yml

@@ -0,0 +1,14 @@
+version: '3.8'
+
+services:
+  docs:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8000:8000"
+    volumes:
+      - .:/docs
+    environment:
+      - PYTHONUNBUFFERED=1
+    restart: unless-stopped

docs/get-started/welcome.md

@@ -23,6 +23,6 @@ Your Quix workflow:
 
     Start building your stream processing pipeline locally on the command line with Quix Streams.
 
-    [Install Quix Streams :octicons-arrow-right-24:](./quix-start.md)
+    [Install Quix Streams :octicons-arrow-right-24:](../quix-streams/quickstart.md)
 
 </div>

mkdocs.yml

@@ -15,7 +15,6 @@ edit_uri: tree/dev/docs
 nav:
   - 'Get started':
     - 'Welcome': 'get-started/welcome.md'
-    - 'Get started!': 'get-started/quix-start.md'
     - 'Core concepts':
       - 'get-started/streaming.md'
       - 'get-started/stream-processing.md'
@@ -822,7 +821,8 @@ plugins:
         'get-started/build-cli.md' : 'cli/cli-quickstart.md'
         'get-started/cli-quickstart.md' : 'cli/cli-quickstart.md'
         'cli/cli-build-pipeline.md' : 'cli/cli-quickstart.md'
-        'get-started/install.md': 'get-started/quix-start.md'
+        'get-started/install.md': 'quix-streams/quickstart.md'
+        'get-started/quix-start.md' : 'quix-streams/quickstart.md'
         'cli/cli-quickstart.md' : 'quix-cli/cli-quickstart.md'
         'cli/overview.md' : 'quix-cli/overview.md'
         'cli/cli-reference.md' : 'quix-cli/overview.md'

open-browser.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+
+# Wait for the service to be ready with a timeout of 2 minutes
+timeout=120
+interval=1
+elapsed=0
+
+echo "Waiting for the documentation server to be ready..."
+while [ $elapsed -lt $timeout ]; do
+    if curl -s -f http://localhost:8000/docs/ > /dev/null; then
+        echo "Server is ready!"
+        break
+    fi
+    sleep $interval
+    elapsed=$((elapsed + interval))
+    echo "Waiting for docs to be ready... ($elapsed seconds elapsed)"
+done
+
+if [ $elapsed -ge $timeout ]; then
+    echo "Timeout reached. Docs did not become ready in $timeout seconds."
+    exit 1
+fi
+
+# Open browser on host machine
+if [[ "$OSTYPE" == "linux-gnu"* ]]; then
+    xdg-open http://localhost:8000/docs/
+elif [[ "$OSTYPE" == "darwin"* ]]; then
+    open http://localhost:8000/docs/
+elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then
+    start http://localhost:8000/docs/
+fi 

requirements.txt

@@ -1,5 +1,7 @@
-mkdocs-multirepo-plugin
-mkdocs-glightbox
-mkdocs-redirects
-mkdocs-include-markdown-plugin
-mkdocs-exclude-search
+mkdocs-material[imaging]>=9.5.0
+mkdocs-glightbox>=0.1.0
+mkdocs-multirepo-plugin>=0.1.0
+mkdocs-redirects>=1.2.0
+mkdocs-include-markdown-plugin>=4.0.4
+mkdocs-exclude-search>=0.6.4
+cffi>=1.15.0