RST Workshop: Docker Environment

These configs provide a basic Docker and Nginx reverse-proxy setup for installing Sphinx. This setup uses volumes to persist the Sphinx data and Nginx configurations, but not the state of the VPS (i.e. installed packages).

Note

These configs assume that Sphinx is installed in directory /opt/sphinx. These settings are highlighted below.

Basic docker-compose.yml config

version: "3.3"

services:
  sphinx:
    image: nginx:latest                           # Debian-based
    container_name: sphinx_nginx
    volumes:
      - ./sphinx:/opt/sphinx                        # Sphinx files
      - ./logs:/var/log/nginx                       # Nginx logs
      - ./nginx/site.conf:/etc/nginx/conf.d/site.conf     # Site conf for FQD
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf          # nginx.conf for custom settings
    ports:
      - 8085:80
    restart: always

‘site.conf’ for sphinx_nginx volume

server {
    index index.html;
    server_name   sphinx.example.com;
    error_log    /var/log/nginx/error.log;
    access_log   /var/log/nginx/access.log;
    root         /opt/sphinx/_build/html;
}

‘nginx.conf’ for sphinx_nginx volume. Security settings and custom log for revere proxy.

user  nginx;
worker_processes  1;

error_log  /var/log/nginx/error.log warn;
pid        /var/run/nginx.pid;

events {
    worker_connections  1024;
}

http {
    ##----- Added by for security ------##
    server_tokens off;

    ##----- End ------##

    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';

    access_log  /var/log/nginx/access.log  main;

    sendfile        on;
    #tcp_nopush     on;

    keepalive_timeout  65;

    #gzip  on;

    include /etc/nginx/conf.d/*.conf;
}

Basic Nginx reverse proxy

server {
    listen 80;

    server_name sphinx.example.com;

    location / {
        proxy_pass http://localhost:8085;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Dockerfile

Here is the Dockerfile that we are using in this site. You will notice some additional packages that are used to render diagrams.

The configuration files listed above will work using an image build from this file.

Note

Updated May 2022 (changed base image to nginx:latest)

FROM nginx:latest

# Install some required libraries
RUN set -ex; \
\
apt-get update; \
apt-get install -y \
            build-essential wget \
            python3-pip

# Install libraries for the diagram extensions
RUN apt-get install -y \
            fonts-dejavu fonts-liberation \
            libjpeg-dev \
            zlib1g-dev \
            libpng-dev \
            graphviz \
            openjdk-11-jre

# Install Sphinx and its requirements
# Downgrade MarkupSafe to fix error : cannot import name 'soft_unicode' from 'markupsafe'
# MarkupSafe==2.0.1
run \
    pip3 install --upgrade pip && \
    pip3 install wheel \
            MarkupSafe==2.0.1 \
            Sphinx \
            sphinx-autobuild \
            sphinx-rtd-theme \
            sphinx-notfound-page \
            sphinx-sitemap \
            sphinx-js

# Add the requirements to install the diagram extensions, then install using pip

# Required for sphinxcontrib-plantuml
RUN wget http://downloads.sourceforge.net/project/plantuml/plantuml.jar -P /opt/ \
    && echo -e '#!/bin/sh -e\njava -jar /opt/plantuml.jar "$@"' > /usr/local/bin/plantuml \
    && chmod +x /usr/local/bin/plantuml

RUN pip3 install sphinxcontrib-actdiag \
                    sphinxcontrib-blockdiag \
                    sphinxcontrib-nwdiag \
                    sphinxcontrib-seqdiag \
                    sphinxcontrib-plantuml

WORKDIR /opt/sphinx

This file was influenced from https://github.com/dldl/sphinx-server