Installing ShareLaTeX
ShareLaTeX Overview
ShareLaTeX is an open-source online real-time collaborative LaTeX editor. This tutorial explains how to install a secure ShareLaTeX instance with an NGINX reverse proxy.
Requirements
- You have an account and are logged into console.scaleway.com
- You have configured your SSH Key
- You have a virtual cloud instance running on Ubuntu Xenial
- For optimal performances it is recommended to run this tutorial at least on a Start1-M instance
Installing Docker
Install ShareLaTeX on a fresh Ubuntu Xenial (16.04) instance. The software runs on Docker. Therefore the Docker environment has to be installed in a first step. Docker exists in two versions: Docker EE (Enterprise Edition) and Docker CE (Community Edition). Docker CE is being used in this tutorial.
1 . Start by installing the required packages, the GPG key and the repository of docker on our instance:
apt-get install apt-transport-https ca-certificates curl software-properties-common python-pip letsencrypt nginx exim4
curl -fsSL https://download.docker.com/linux/debian/gpg | apt-key add -
add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
2 . Update apt and launch the installation of Docker:
apt-get update
apt-get install docker-ce
3 . Install docker-compose, a python tool which can be installed via pip:
pip install docker-compose
The tool is used to manage the different services we need on our server.
Docker Community Edition is installed on the server now.
Configuring ShareLaTeX
ShareLaTeX relies on two external services that are not installed by default. They will also be provided via Docker: MongoDB and Redis.
Docker-compose is installed on the server to manage the dependencies between the different services. It will start and stop all required applications.
ShareLaTeX provides a pre-configured configuration file that can be used with docker-compose.
1 . Create a directory and download the file:
mkdir /etc/sharelatex
cd /etc/sharelatex
wget https://raw.githubusercontent.com/sharelatex/sharelatex/master/docker-compose.yml
The software stores all files by default in the home directory of the user.
2 . To have the data of each service stored in a dedicated directory, create a directory /var/lib/sharelatex with the following sub-folders:
mkdir /var/lib/sharelatex
mkdir /var/lib/sharelatex/data
mkdir /var/lib/sharelatex/mongodb
mkdir /var/lib/sharelatex/redis
3 . Tell docker-compose to store the data in these folders.
4 . Open the file /etc/sharelatex/docker-compose.yml in a text editor and modify it as follows:
volumes:
- ~/sharelatex_data:/var/lib/sharelatex
These lines provide the information where ShareLateX will store the data. The part before the : represents the path on the host, the part after the double-point represents the path in the container. Edit the local part so that it will look like this:
volumes:
- /var/lib/sharelatex/data:/var/lib/sharelatex
Attention! Never edit the second path as it represents the path inside the container. If you modify it, your data will not be saved correctly and you risk data loss!
5 . Make the same modification for MongoDB and Redis. The file should look like this:
volumes:
- /var/lib/sharelatex/mongodb:/data/db
volumes:
- /var/lib/sharelatex/redis:/data
6 . To run ShareLaTeX behind an NGINX reverse proxy, edit the port on which the application listens:
ports:
- 80:80
7 . Make sure that the application listens on port 4242 and is available only from the IP 127.0.0.1, the host itself. This ensures the application can only be accessed via our HTTPS proxy for security reasons from the outside world. Therefore we modify it like this:
ports:
- 127.0.0.1:4242:80
8 . Scroll down in the file, to a part called environment. This part contains the configuration of ShareLateX, modify it as follows:
environment:
SHARELATEX_MONGO_URL: mongodb://mongo/sharelatex
SHARELATEX_REDIS_HOST: redis
SHARELATEX_APP_NAME: ShareLaTeX
# Put here the information about your ShareLaTeX site:
SHARELATEX_SITE_URL: https://my.sharelatex.tld
SHARELATEX_NAV_TITLE: ShareLaTeX - My beautiful ShareLaTeX Installation
# Uncomment the following line if you want to display a logo (i.e., of your school or university)
# SHARELATEX_HEADER_IMAGE_URL: http://somewhere.com/mylogo.png
# Put your email address here:
SHARELATEX_ADMIN_EMAIL: my@email.com
SHARELATEX_LEFT_FOOTER: '[{"text": "Powered by <a href=\"https://github.com/sharelatex/sharelatex\">ShareLaTeX</a>"}]'
SHARELATEX_RIGHT_FOOTER: '[{"text": "Run your own instance on <a href=\"https://scaleway.com\">Scaleway</a>"} ]'
# Configure the email address that will be displayed in emails sent by ShareLaTeX
SHARELATEX_EMAIL_FROM_ADDRESS: "my@email.com"
# Enable the installation behind a proxy
SHARELATEX_BEHIND_PROXY: 'true'
SHARELATEX_SECURE_COOKIE: 'true'
# Set the language of the installation. For example 'en' English, 'de' German, 'fr' French ...
SHARELATEX_SITE_LANGUAGE: 'en'
# Configure the settings for outgoing mails
SHARELATEX_EMAIL_SMTP_HOST: 'localhost'
SHARELATEX_EMAIL_SMTP_PORT: '465'
SHARELATEX_EMAIL_SMTP_SECURE: 'true'
SHARELATEX_EMAIL_SMTP_USER: 'sharelatex'
SHARELATEX_EMAIL_SMTP_PASS: 'YOUR_PASSWORD'
# SHARELATEX_EMAIL_SMTP_TLS_REJECT_UNAUTH: 'true'
# SHARELATEX_EMAIL_SMTP_IGNORE_TLS: 'false'
# Set a footer for outgoing mails:
SHARELATEX_CUSTOM_EMAIL_FOOTER: "<div>Powered by ShareLaTeX</div>"
Hint: The configuration file is written in YAML. Make sure to respect the YAML formatting, otherwise starting ShareLaTeX may fail.
Configuring Nginx
This tutorial uses NGINX with Let’s Encrypt and CertBot as an SSL enabled reverse proxy to secure the connection between the client and our server.
1 . Install Certbot on the server:
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-nginx
2 . Generate the certificate, by running the following command:
sudo certbot --nginx certonly
SSL certificates issued by Let’s Encrypt are valid for 90 days. Certbot comes with the option to automatically renew the certificate.
Configure a cron job that launches Certbot daily to check the status of the certificate.
3 . Open the crontab by typing:
crontab -e
4 . Add the following line which will stop Nginx, renew the certificate and restart the web server daily at 4:30 in the morning:
30 4 * * * /opt/letsencrypt/certbot-auto renew --pre-hook "service nginx stop" --post-hook "service nginx start"
Configure Nginx in a way, that it will serve our ShareLaTeX site as default site:
5 . Edit the file /etc/nginx/sites-enabled/default so that it looks like the following example:
server {
listen 80;
listen [::]:80;
server_name my.sharelatex.tld;
location / {
return 301 https://$server_name$request_uri;
}
}
server {
listen [::]:443 ssl ipv6only=on;
listen 443 ssl;
server_name my.sharelatex.tld;
ssl_certificate /etc/letsencrypt/live/my.sharelatex.tld/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/my.sharelatex.tld/privkey.pem;
include /etc/letsencrypt/options-ssl-nginx.conf;
ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem;
proxy_set_header X-Forwarded-For $remote_addr;
add_header Strict-Transport-Security "max-age=31536000; includeSubDomains";
server_tokens off;
add_header X-Frame-Options SAMEORIGIN;
add_header X-Content-Type-Options nosniff;
client_max_body_size 50M;
location / {
proxy_pass http://localhost:4242;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 3m;
proxy_send_timeout 3m;
access_log /var/log/nginx/sharelatex.access.log;
error_log /var/log/nginx/sharelatex.error.log;
}
}
6 . Restart Nginx with the following command:
service nginx restart
Configuring Systemd
Everything is ready for the first start of the ShareLaTeX instance now. To ensure that ShareLaTeX automatically starts on each reboot of the server, create a systemd script for it.
1 . Create the file /etc/systemd/system/sharelatex.service and open it in a text editor. The systemd script should look like the following example:
[Unit]
Description=ShareLaTeX Service
After=docker.service
[Service]
Type=simple
WorkingDirectory=/etc/sharelatex
ExecStart=/usr/local/bin/docker-compose -f /etc/sharelatex/docker-compose.yml up
ExecStop=/usr/local/bin/docker-compose -f /etc/sharelatex/docker-compose.yml down
[Install]
WantedBy=multi-user.target
2 . Save the file and make the new service known to the system:
systemctl enable sharelatex
systemctl daemon-reload
3 . Start the service service sharelatex start and access ShareLaTeX with a web browser: https://my.instance.ip.address/
The following interface appears: 
Creating the First User
The instance is running now, but does not have any user yet.
1 . Create the first admin user with the following command:
$ docker exec sharelatex /bin/bash -c "cd /var/www/sharelatex; grunt user:create-admin --email my@email.address"
Some messages appear during the user creation, it has finished when the following message appears:
Successfully created my@email.address as an admin user.
Please visit the following URL to set a password for my@email.address and log in:
https://my.sharelatex.tld/user/password/set?passwordResetToken=79d16b0b75a24e2f7cb3174df638d492f4a427e5f88f8fe34aa14373fe6c8630
Once the password for the user has been set, login with your email address and your password.
2 . Create a first project:
Installing Additional LaTex Packages
The installation is fully operational, but there are only a few LaTeX packages installed to save disk space. It is possible to install the missing packages (i.e. Beamer, XeTeX or AMS-Math), to be able to compile almost any LaTeX document.
Hint: The installation of all additional packages can take several hours. It is recommended to run it in a screen session, so the installation will continue if the SSH connection gets interrupted.
1 . To install screen, run the following command:
apt-get install screen
2 . Launch the installation of the additional packages:
screen
docker exec sharelatex tlmgr install scheme-full
It is possible to close the SSH client and to recover the session later with screen -r for checking the status of the installation.
Once it has finished, exit the screen session with exit.
As changes to Docker containers are not permanent, it is required to commit* a new version of the ShareLaTeX container which contains the modification.
To do this,the ID of the container is required.
3 . To get it, type the following command:
docker ps
The following output of running docker containers on the system appears:
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
266d633cb0d9 sharelatex/sharelatex "/sbin/my_init" About an hour ago Up About an hour 127.0.0.1:4242->80/tcp sharelatex
f50df9f39bbd mongo "docker-entrypoint.s…" About an hour ago Up About an hour 27017/tcp mongo
b886c9d0f3da redis "docker-entrypoint.s…" About an hour ago Up About an hour 6379/tcp redis
The sharelatex container has the ID 266d633cb0d94.
4 . Build a new container with the LaTeX modules installed, by typing:
docker commit -m "installing all latex packages" 266d633cb0d9 sharelatex/sharelatex:v3
This may take some minutes before the new container is ready.
Once the container is built, tell docker-compose to use this new container by default.
5 . To do this, edit the image information in the file /etc/sharelatex/docker-compose.yml:
version: '2'
services:
sharelatex:
restart: always
image: sharelatex/sharelatex:v3
Note: Once a new image has been built, it will not be updated automatically. Rebuild the image manually to update the container.