docs: fixed some build errors

docs/admin/sec-sophos-umc.rst

@@ -1,101 +1,101 b''
-.. _sec-your-server:
+.. _sec-sophos-umc:
 
 Securing Your Server via Sophos UTM 9
 -------------------------------------
 
 
 
 Below is an example configuration for Sophos UTM 9 Webserver Protection::
 
     Sophos UTM 9 Webserver Protection
     Web Application Firewall based on apache2 modesecurity2
     --------------------------------------------------
     1. Firewall Profiles -> Firewall Profile
     --------------------------------------------------
     Name: RhodeCode (can be anything)
     Mode: Reject
     Hardening & Signing:
         [ ] Static URL hardeninig
         [ ] Form hardening
         [x] Cookie Signing
     Filtering:
         [x] Block clients with bad reputation
         [x] Common Threats Filter
         [ ] Rigid Filtering
             Skip Filter Rules:
                 960015
                 950120
                 981173
                 970901
                 960010
                 960032
                 960035
                 958291
                 970903
                 970003
     Common Threat Filter Categories:
         [x] Protocol violations
         [x] Protocol anomalies
         [x] Request limit
         [x] HTTP policy
         [x] Bad robots
         [x] Generic attacks
         [x] SQL injection attacks
         [x] XSS attacks
         [x] Tight security
         [x] Trojans
         [x] Outbound
     Scanning:
         [ ] Enable antivirus scanning
         [ ] Block uploads by MIME type
     --------------------------------------------------
     2. Web Application Firewall -> Real Webservers
     --------------------------------------------------
     Name: RhodeCode (can be anything)
     Host: Your RhodeCode-Server (UTM object)
     Type: Encrypted (HTTPS)
     Port: 443
     --------------------------------------------------
     3. Web Application Firewall -> Virual Webservers
     --------------------------------------------------
     Name: RhodeCode (can be anything)
     Interface: WAN (your WAN interface)
     Type: Encrypted (HTTPS) & redirect
     Certificate: Wildcard or matching domain certificate
         Domains (in case of Wildcard certificate):
             rhodecode.yourcompany.com (match your DNS configuration)
             gist.yourcompany.com (match your DNS & RhodeCode configuration)
     Real Webservers for path '/':
         [x] RhodeCode (created in step 2)
     Firewall: RhodeCode (created in step 1)
     --------------------------------------------------
     4. Firewall Profiles -> Exceptions
     --------------------------------------------------
     Name: RhodeCode exceptions (can be anything)
     Skip these checks:
         [ ] Cookie signing
         [ ] Static URL Hardening
         [ ] Form hardening
         [x] Antivirus scanning
         [x] True file type control
         [ ] Block clients with bad reputation
     Skip these categories:
         [ ] Protocol violations
         [x] Protocol anomalies
         [x] Request limits
         [ ] HTTP policy
         [ ] Bad robots
         [ ] Generic attacks
         [ ] SQL injection attacks
         [ ] XSS attacks
         [ ] Tight security
         [ ] Trojans
         [x] Outbound
     Virtual Webservers:
         [x] RhodeCode (created in step 3)
     For All Requests:
         Web requests matching this pattern:
             /_channelstream/ws
             /Repository1/*
             /Repository2/*
             /Repository3/*
  No newline at end of file

docs/conf.py

@@ -1,317 +1,317 b''
 # -*- coding: utf-8 -*-
 #
 # RhodeCode Enterprise documentation build configuration file, created by
 # sphinx-quickstart on Tue Nov  4 11:48:37 2014.
 #
 # This file is execfile()d with the current directory set to its
 # containing dir.
 #
 # Note that not all possible configuration values are present in this
 # autogenerated file.
 #
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
 import sys
 import os
 import datetime
 import sphinx_rtd_theme
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('.'))
 import common
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
 #needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
     'sphinx.ext.todo',
-    'sphinx.ext.pngmath'
+    'sphinx.ext.imgmath'
 ]
 
 intersphinx_mapping = {
     'enterprise': ('https://docs.rhodecode.com/RhodeCode-Enterprise/', None),
     'control': ('https://docs.rhodecode.com/RhodeCode-Control/', None),
 }
 
 if tags.has('dev'):
     intersphinx_mapping.update({
         'enterprise': ('https://ci.rhodecode.com/documentation/Momentum/', None),
         'control': ('https://ci.rhodecode.com/documentation/Control/', None),
     })
 
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
 
 # The master toctree document.
 master_doc = 'index'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 
 # TODO: johbo: Move into common package for documentation utilities
 def _get_version():
     with open('../rhodecode/VERSION') as f:
         return f.read().strip()
 
 # The full version, including alpha/beta/rc tags.
 release = _get_version()
 # The short X.Y version.
 version = '.'.join(release.split('.', 2)[:2])  # First two parts of release
 
 # General information about the project.
 project = u'RhodeCode Enterprise %s ' % _get_version()
 copyright = u'2010-{now.year}, RhodeCode GmbH'.format(
     now=datetime.datetime.today())
 
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #language = None
 
 rst_epilog = common.rst_epilog + """
 .. |async| replace:: asynchronous
 """
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 #today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 exclude_patterns = [
     # Special directories
     '_build',
     'result',
 
     # Other RST files
     'admin/rhodecode-backup.rst',
     'auth/ldap-configuration-example.rst',
     'issue-trackers/redmine.rst',
     'known-issues/error-msg-guide.rst',
     'tutorials/docs-build.rst',
     'integrations/example-ext.py',
     'collaboration/supported-workflows.rst',
 ]
 
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #default_role = None
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
 
 # If true, keep warnings as "system message" paragraphs in the built documents.
 keep_warnings = tags.has("dev")
 
 
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #html_theme = 'rctheme'
 html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
 #html_theme_options = {}
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Add any paths that contain custom themes here, relative to this directory.
 #html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # A shorter title for the navigation bar.  Default is the same as html_title.
 #html_short_title = None
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
 #html_logo = None
 html_sidebars = {
    '**': ['globaltoc.html'],
 }
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
 html_favicon = 'images/favicon.ico'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['static/css/add.css']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 #html_extra_path = []
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
 
 # If false, no module index is generated.
 #html_domain_indices = True
 
 # If false, no index is generated.
 #html_use_index = True
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False
 
 # If true, links to the reST sources are added to the pages.
 #html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
 #html_show_copyright = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'rhodecode-enterprise'
 
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
     'classoptions': ',oneside',
     'babel': '\\usepackage[english]{babel}',
 
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
 
 # The font size ('10pt', '11pt' or '12pt').
 #'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
   ('index', 'RhodeCodeEnterprise.tex', u'RhodeCode Enterprise',
    u'RhodeCode GmbH', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 
 # If true, show page references after internal links.
 latex_show_pagerefs = True
 
 # If true, show URL addresses after external links.
 latex_show_urls = 'footnote'
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
 #latex_domain_indices = True
 
 # Mode for literal blocks wider than the frame. Can be
 # overflow, shrink or truncate
 pdf_fit_mode = "truncate"
 
 
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'rhodecodeenterprise', u'RhodeCode Enterprise',
      [u'RhodeCode GmbH'], 1)
 ]
 
 # If true, show URL addresses after external links.
 #man_show_urls = False
 
 
 # -- Options for Texinfo output -------------------------------------------
 
 # Grouping the document tree into Texinfo files. List of tuples
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'RhodeCodeEnterprise', u'RhodeCode Enterprise',
    u'RhodeCode Docs Team', 'RhodeCodeEnterprise', 'RhodeCode Docs Project',
    'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
 #texinfo_appendices = []
 
 # If false, no module index is generated.
 #texinfo_domain_indices = True
 
 # How to display URL addresses: 'footnote', 'no', or 'inline'.
 #texinfo_show_urls = 'footnote'
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
 # We want to see todo notes in case of a pre-release build of the documentation
 todo_include_todos = tags.has("dev")

docs/tutorials/deploy-from-host.rst

@@ -1,220 +1,220 b''
 .. _hosted-solution:
 
 Deploy |RCE| From a Hosted Server
 =================================
 
 If you wish to deploy your own |RCE| instance from something like a
 `Digital Ocean`_ droplet, or a `hetzner`_ server use the following
 instructions to get it setup.
 
 I'm using an Ubuntu 14.04 image for the purposes of this
 tutorial, but all other Unix environments will be pretty similar. You can
 check out the full lists of supported platforms and versions in the
 :ref:`system-overview-ref` section.
 
 
 Create a Digital Ocean Droplet
 ------------------------------
 
 1. Sign into Digital Ocean.
 2. Create a Droplet choosing Ubuntu 14.04 as your |os|.
 3. (Optional) Add SSH keys if you have them set up.
 
 Configure Your Server
 ---------------------
 
 Once you have your server created, you need to sign into it and set it up to
 host |RCE|.
 
 1. Open a terminal and sign into your server. Digital Ocean will mail you the
    IP address. You'll need to change your password on the first login if you
    don not have SSH keys set up.
 
 .. code-block:: bash
 
     $ ssh root@203.0.113.113
 
 2. It is not advised to install |RCE| as the ``root`` user. So create a user
    with sudo permissions and then carry out the rest of the steps from that user
    account.
 
 .. code-block:: bash
 
     # Create a user with sudo permissions
     root@rhodecode:~# sudo useradd -m -s /bin/bash -d /home/brian -U brian
     root@rhodecode:~# sudo usermod -a -G sudo brian
 
     # Set the password for that user
     root@rhodecode:~# passwd brian
     Enter new UNIX password:
     Retype new UNIX password:
     passwd: password updated successfully
 
     # Switch to that user for the rest of the steps
     root@rhodecode:~# su brian
 
     # You should see your home dir change to what was set during installation
     brian@rhodecode:~$ cd ~
     brian@rhodecode:~$ pwd
     /home/brian
 
 Once you have this set up, you are ready to install |RCC|.
 
 Install |RCC|
 -------------
 
 |RCC| will install and manage the package dependencies for your |RCE| instance.
 
 1. Download the |RCC| installer from https://rhodecode.com/download/
 2. Once downloaded to your computer, transfer the package to your server
 
 .. note::
 
    These steps happen on your computer, not on the server.
 
 .. code-block:: bash
 
     # Change to where the file is downloaded
     $ cd Downloads/
 
     # SFTP to your server
     $ sftp brian@203.0.113.113
 
     # Use mput to transfer the file
     sftp> mput RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3
     Uploading RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3 to /home/brian/RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3
     RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d 100%  289MB   4.1MB/s   01:11
     sftp> exit
 
 The |RCC| installer is now on your server, and you can read the full
 instructions here
-:ref:`Install RhodeCode Control <control:rcc-install-ref>`,
+:ref:`Install RhodeCode Control <control:rcc-linux-ref>` ,
 but below is the example shortcut.
 
 .. code-block:: bash
 
     # Check that the script is uploaded to your home directory
     $ ls -1
     RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3
 
     # Change the script permissions
     $ chmod 755 RhodeCode-installer-linux*
 
     # Run the installer and accept the prompts
     $ ./RhodeCode-installer-linux-*
 
 .. important::
 
    Once finished, exit the terminal and sign in again. This is to refresh you
    session to pick up the new commands.
 
 Install |RCE|
 -------------
 
 Now that |RCC| is installed, you can install |RCE|. For the full
 instructions, see
 :ref:`Install RhodeCode Enterprise <control:rce-cli-install-ref>`,
 but the below is an example shortcut.
 
 .. code-block:: bash
 
     # Install a VCS Server and follow the prompts
     $ rccontrol install VCSServer --start-at-boot
 
     Extracting VCSServer ...
     Configuring RhodeCode VCS Server ...
     Supervisord state is: RUNNING
     Added process group vcsserver-1
 
     # Install a RhodeCode Enterprise instance and follow the prompts
     $ rccontrol install Enterprise --start-at-boot
 
     Configuration of RhodeCode Enterprise passed.
     Supervisord state is: RUNNING
     Added process group enterprise-1
 
 |RCE| is now installed on your server, and is running on the port displayed
 by the ``rccontrol status`` command.
 
 .. code-block:: bash
 
     brian@rhodecode:~$ rccontrol status
 
      - NAME: enterprise-1
      - STATUS: RUNNING
      - TYPE: Enterprise
      - VERSION: 3.1.1
      - URL: http://127.0.0.1:10002
 
      - NAME: vcsserver-1
      - STATUS: RUNNING
      - TYPE: VCSServer
      - VERSION: 1.1.1
      - URL: http://127.0.0.1:10001
 
 Serve |RCE| using Nginx
 -----------------------
 
 Now that |RCE| is running, you need to use Nginx or Apache to serve it to
 users. For detailed instructions about setting up your webserver, see the
 :ref:`rhodecode-admin-ref` section. But the below shortcut should help serve
 it.
 
 1. Install Nginx on your server.
 
 .. code-block:: bash
 
     # Install nginx
     $ sudo apt-get install nginx
 
 2. Create a virtual hosts file for RhodeCode Enterprise. Create
    the file in this location :file:`/etc/nginx/sites-available`. In this demo
    I have called it ``vcs.conf``
 
 .. code-block:: bash
 
    # Create the file
    $ sudo vi /etc/nginx/sites-available/vcs.conf
 
 Use the following example to create yours.
 
 .. code-block:: nginx
 
     server {
         listen 80;
         # Change to your IP, or a domain name if you've set that up
         server_name     203.0.113.113 ;
 
         location / {
         # Set this line to match the RhodeCode Enterprise Instance URL
             proxy_pass		http://127.0.0.1:10002/;
             proxy_set_header	Host $Host;
             proxy_buffering		off;
         # Setting this to a high number allows large repo pushes
             client_max_body_size	4G;
             }
         }
 
 3. Symlink the virtual hosts file to the ``sites-enabled`` folder,
    and then restart Nginx.
 
 .. code-block:: bash
 
    # Symlink the virtual hosts file
    $ ln -s /etc/nginx/sites-available/vcs.conf /etc/nginx/sites-enabled/vcs.conf
 
    # You can also delete the Nginx default symlink
    $ rm /etc/nginx/sites-enabled/default
 
    # Restart Nginx
    $ sudo  /etc/init.d/nginx restart
      * Restarting nginx nginx                                     [ OK ]
 
 Once restarted, you should see a clean |RCE| instance running on the IP
 address, or the domain you have set up.
 
 .. image:: ../images/clean-rce.png
    :alt: A fresh RhodeCode Enterprise Instance
 
 .. _Digital Ocean: https://www.digitalocean.com/
 .. _hetzner: https://www.hetzner.de/en/