Deployment Guide - MkDocs Documentation¶

This guide explains how to deploy and manage the Ta-SIEMPlus documentation site.

🚀 Quick Start¶

Local Development¶

Install dependencies:

pip install mkdocs mkdocs-material mike pymdown-extensions

Serve locally:
```
mkdocs serve
```
Site will be available at http://localhost:8000
Build static site:
```
mkdocs build
```
Output will be in site/ directory

Docker Deployment¶

Using Docker Compose (Recommended)¶

Build and start:
```
docker-compose up -d
```
Access the site:
URL: http://localhost:8080
Health check: http://localhost:8080/health
View logs:
```
docker-compose logs -f docs
```
Stop:
```
docker-compose down
```

Using Docker directly¶

Build image:

docker build -f Dockerfile.mkdocs -t ta-siemplus-docs:latest .

Run container:

docker run -d -p 8080:80 --name ta-siemplus-docs ta-siemplus-docs:latest

Stop and remove:

docker stop ta-siemplus-docs
docker rm ta-siemplus-docs

📚 Versioning with Mike¶

Mike is used to manage documentation versions for different Wazuh releases.

Deploy a Version¶

# Deploy version 4.12 and set as latest
mike deploy 4.12 latest --update-aliases

# Deploy version 4.11
mike deploy 4.11

# Deploy and push to gh-pages branch (for GitHub Pages)
mike deploy 4.12 latest --push --update-aliases

Set Default Version¶

mike set-default latest

List Versions¶

mike list

Delete a Version¶

mike delete 4.11

Serve Versioned Docs Locally¶

mike serve

🔧 Configuration¶

Site Settings¶

Edit mkdocs.yml to configure: - Site name and description - Theme settings (colors, fonts, features) - Navigation structure - Plugins and extensions

The navigation is defined in mkdocs.yml under the nav key:

nav:
  - Home: index.md
  - Overview:
    - overview/index.md
  - Runbooks:
    - runbooks/index.md
    - ...

To add a new page: 1. Create the markdown file 2. Add it to the navigation in mkdocs.yml 3. Rebuild the site

Theme Customization¶

Colors¶

Edit mkdocs.yml:

theme:
  palette:
    primary: indigo  # Change to: red, pink, purple, etc.
    accent: indigo   # Change to match primary

Features¶

Enable/disable features in mkdocs.yml:

theme:
  features:
    - navigation.tabs        # Top-level tabs
    - navigation.sections    # Section headers
    - search.suggest        # Search suggestions
    - content.code.copy     # Copy code button

Custom CSS and JavaScript¶

Add custom styles in docs/stylesheets/extra.css
Add custom scripts in docs/javascripts/extra.js

These are automatically included via mkdocs.yml.

🌐 Production Deployment¶

GitHub Pages¶

Enable GitHub Pages in repository settings

Deploy with mike:

mike deploy --push --update-aliases 4.12 latest

Custom Server¶

Build the site:
```
mkdocs build
```

Copy site/ directory to your web server:

rsync -av site/ user@server:/var/www/docs/

Configure Nginx (already included in nginx.conf)

Container Registry¶

Tag image:

docker tag ta-siemplus-docs:latest registry.example.com/ta-siemplus-docs:latest

Push to registry:

docker push registry.example.com/ta-siemplus-docs:latest

Deploy on server:

docker pull registry.example.com/ta-siemplus-docs:latest
docker run -d -p 80:80 registry.example.com/ta-siemplus-docs:latest

🔄 Update Workflow¶

When Content Changes¶

Edit markdown files in appropriate directory
Test locally:
```
mkdocs serve
```
Commit and push to repository
Rebuild Docker image (if using Docker):
```
docker-compose up -d --build
```

When Adding New Runbook/Checklist¶

Create the markdown file in appropriate directory
Update navigation in mkdocs.yml
Add to index page of the section
Test locally to verify links
Commit and push

For New Wazuh Version¶

Create version directory:
```
mkdir -p docs/upgrade-guides/4.13
```

Create version content:

cp docs/upgrade-guides/4.12/index.md docs/upgrade-guides/4.13/index.md

Update content for new version
Add to navigation in mkdocs.yml

Deploy version:

mike deploy 4.13 latest --update-aliases

📊 Monitoring¶

Health Checks¶

The Nginx configuration includes a health endpoint:

curl http://localhost:8080/health
# Should return: healthy

Docker Health¶

docker ps --format "table {{.Names}}\t{{.Status}}"

Logs¶

# Docker Compose
docker-compose logs -f docs

# Docker
docker logs -f ta-siemplus-docs

# Nginx access log
docker exec ta-siemplus-docs tail -f /var/log/nginx/access.log

# Nginx error log
docker exec ta-siemplus-docs tail -f /var/log/nginx/error.log

🔐 Security Considerations¶

Content Security¶

Never commit secrets to documentation
Use vault references: vault://path/to/secret
Review all PRs before merging

Container Security¶

Use official base images
Keep dependencies updated
Run containers as non-root (Nginx already does this)
Use read-only filesystem where possible

Network Security¶

Use HTTPS in production (add SSL termination)
Configure firewall rules
Consider authentication if needed (use reverse proxy)

🛠️ Troubleshooting¶

Build Errors¶

# Clear cache and rebuild
rm -rf site/ .cache/
mkdocs build --strict

Docker Issues¶

# Rebuild without cache
docker-compose build --no-cache

# Check container logs
docker-compose logs docs

# Restart container
docker-compose restart docs

Check mkdocs.yml syntax
Verify file paths are correct
Clear browser cache
Rebuild site

Mike Version Issues¶

# List deployed versions
mike list

# Rebuild specific version
mike deploy 4.12 --update-aliases

# Force delete and redeploy
mike delete 4.12
mike deploy 4.12 latest