Skip to content

Replace getting started with one from Quix-Streams #488

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Apr 10, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
124 changes: 100 additions & 24 deletions RUNNING-DOCS-LOCALLY.md
Original file line number Diff line number Diff line change
@@ -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
```
14 changes: 14 additions & 0 deletions docker-compose.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
version: '3.8'

services:
docs:
build:
context: .
dockerfile: Dockerfile
ports:
- "8000:8000"
volumes:
- .:/docs
environment:
- PYTHONUNBUFFERED=1
restart: unless-stopped
93 changes: 0 additions & 93 deletions docs/get-started/quix-start.md

This file was deleted.

2 changes: 1 addition & 1 deletion docs/get-started/welcome.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
4 changes: 2 additions & 2 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down Expand Up @@ -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'
Expand Down
31 changes: 31 additions & 0 deletions open-browser.sh
Original file line number Diff line number Diff line change
@@ -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
12 changes: 7 additions & 5 deletions requirements.txt
Original file line number Diff line number Diff line change
@@ -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