.. _Sphinx Docker Environment:

********************************
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.


.. code-block:: bash
    :caption: Basic docker-compose.yml config
    :linenos:
    :emphasize-lines: 8

    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


.. code-block:: bash
    :caption: 'site.conf' for sphinx_nginx volume
    :linenos:
    :emphasize-lines: 3, 6

    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;
    }


.. code-block:: bash
    :caption: 'nginx.conf' for sphinx_nginx volume. Security settings
        and custom log for revere proxy.
    :linenos:
    :emphasize-lines: 13, 20

    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;
    }


.. code-block:: bash
    :caption: Basic Nginx reverse proxy
    :linenos:
    :emphasize-lines: 4

    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)

.. code-block:: docker

    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