Local Install¶

Before proceeding to setup your own local Read the Docs instance, it may be worth familiarizing yourself with the Read the Docs development setup and standards, which details the local development setup with Docker, and the installation guide.

Again, if your primary reasons for considering a private installation are to connect to private repositories or to have fine grained access control over your documentation, please consider Read the Docs for Business. It has those features and many more and helps support Read the Docs!

Assumptions and Prerequisites¶

Debian VM provisioned with python 2.7.x
All python dependencies and setup tools are installed:

sudo apt-get install python-setuptools
sudo apt-get install build-essential
sudo apt-get install python-dev
sudo apt-get install libevent-dev
sudo easy_install pip

Git:

sudo apt-get install git

Git repo is git.corp.company.com:git/docs/documentation.git
Source documents are in ../docs/source
Sphinx:

sudo pip install sphinx

Note

Not using sudo may prevent access. “error: could not create ‘/usr/local/lib/python2.7/dist-packages/markupsafe’: Permission denied”

Local RTD Setup¶

Install RTD¶

To host your documentation on a local RTD installation, set it up in your VM:

mkdir checkouts
cd checkouts
git clone https://github.com/readthedocs/readthedocs.org.git
cd readthedocs.org
sudo pip install -r requirements.txt

Possible errors with a local RTD setup¶

Error: error: command 'gcc' failed with exit status 1

Resolution: Run the following commands:

sudo apt-get update
sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-devel libxslt-devel
sudo apt-get build-dep python-imaging --fix-missing

On Debian 8 (jessie) the command is slightly different:

sudo apt-get update
sudo apt-get install python2.7-dev tk8.5 tcl8.5 tk8.5-dev tcl8.5-dev libxml2-dev libxslt-dev
sudo apt-get build-dep python-imaging --fix-missing

Also don’t forget to re-run the dependency installation

sudo pip install -r requirements.txt

Configure the RTD Server and Superuser¶

Run the following commands:

./manage.py migrate
./manage.py createsuperuser

This will prompt you to create a superuser account for Django. Enter appropriate details. For example:
```
Username: monami.b
Email address: monami.b@email.com
Password: pa$$word
```

RTD Server Administration¶

Navigate to the ../checkouts/readthedocs.org folder in your VM and run the following command:

./manage.py runserver [VM IP ADDRESS]:8000
curl -i http://[VM IP ADDRESS]:8000

You should now be able to log into the admin interface from any PC in your LAN at http://[VM IP ADDRESS]:8000/admin using the superuser account created in django.

Go to the dashboard at http://[VM IP ADDRESS]:8000/dashboard and follow these steps:

Point the repository to your corporate Git project where the documentation source is checked in. Example: git.corp.company.com:/git/docs/documentation.git.
Clone the documentation sources from Git in the VM.
Navigate to the root path for documentation.
Run the following Sphinx commands:

make html

This generates the HTML documentation site using the default Sphinx theme. Verify the output in your local documentation folder under ../build/html

Possible errors administering a RTD server¶

Error: Couldn’t access Git Corp from VM.

Resolution: The primary access may be set from your base PC/laptop. You will need to configure your RSA keys in the VM.

Workaround-1

In your machine, navigate to the .ssh folder:
```
cd .ssh/
cat id_rsa
```
Copy the entire Private Key.
Now, SSH to the VM.
Open the id_rsa file in the VM:
```
vim /home/<username>/.ssh/id_rsa
```
Paste the RSA key copied from your machine and save file (Esc. :wq!).

Workaround 2

SSH to the VM using the -A directive:

ssh document-vm -A

This provides all permissions for that particular remote session, which are revoked when you logout.

Build Documentation on Local RTD Instance¶

Log into http://[VM IP ADDRESS]:[PORT] using the django superuser creds and follow these steps.

For a new project¶

Select <username> > Add Project from the user menu.
Click Manually Import Project.
Provide the following information in the Project Details page:
- Name: Appropriate name for the documentation project. For example – API Docs Project
- Repository URL: URL to the documentation project. For example - git.corp.company.com:/git/docs/documentation.git
- Repository Type: Git
Select the Edit advanced project options checkbox.
Click Next.

For an existing project¶

Select <username> > Projects from the user menu.
Select the relevant project from the Projects list.
Select latest from the Build a version dropdown.
Click Build. This will take you to the Builds tab where the progress status is displayed. This may take some time.

Tips¶

If the installation doesn’t work on VM using your login/LDAP credentials, try running the operations as root (su).