quick-start-guide.md

Quick-Start Guide

Prerequisites

The Overleaf Toolkit depends on the following programs:

• bash
• docker

We recommend that you install the most recent version of docker that is available on your system.

Install

First, let's clone this git repository to your machine:

$ git clone https://github.com/overleaf/toolkit.git ./overleaf-toolkit

Next let's move into this directory:

$ cd ./overleaf-toolkit

For the rest of this guide, we will assume that you will run all subsequent commands from this directory.

Take a Look Around

Let's take a look at the structure of the repository:

$ ls -l

Which will print something like this:

    bin
    CHANGELOG.md
    config
    data
    doc
    lib
    LICENSE
    README.md

The README.md file contains some useful information about the project, while the doc directory contains all of the documentation you will need to use the toolkit. The config directory will contain your own local configuration files (which we will create in just a moment), while the bin directory contains a collection of scripts that manage your overleaf instance.

Initialise Configuration

Let's create our local configuration, by running bin/init:

$ bin/init

Now check the contents of the config/ directory

$ ls config
overleaf.rc     variables.env     version

These are the three configuration files you will interact with:

• overleaf.rc : the main top-level configuration file
• variables.env : environment variables loaded into the docker container
• version : the version of the docker images to use

Starting Up

The Overleaf Toolkit uses docker compose to manage the overleaf docker containers. The toolkit provides a set of scripts which wrap docker compose, and take care of most of the details for you.

Let's start the docker services:

$ bin/up

You should see some log output from the docker containers, indicating that the containers are running. If you press CTRL-C at the terminal, the services will shut down. You can start them up again (without attaching to the log output) by running bin/start. More generally, you can run bin/docker-compose to control the docker compose system directly, if you find that the convenience scripts don't cover your use-case.

Create the first admin account

In a browser, open http://localhost/launchpad. You should see a form with email and password fields. Fill these in with the credentials you want to use as the admin account, then click "Register".

Then click the link to go to the login page (http://localhost/login). Enter the credentials. Once you are logged in, you will be taken to a welcome page.

Click the green button at the bottom of the page to start using Overleaf.

Create your first project

On the http://localhost/project page, you will see a button prompting you to create your first project. Click the button and follow the instructions.

You should then be taken to the new project, where you will see a text editor and a PDF preview.

(Optional) Check the logs

Let's look at the logs inside the container:

$ bin/logs -f web

You can also look at the logs for multiple services at once:

$ bin/logs -f filestore docstore web clsi

TLS Proxy

The Overleaf Toolkit includes optional configuration to run an NGINX proxy, which presents Server Pro over HTTPS. Initial configuration can be generated by running

bin/init --tls

This creates minimal NGINX config in config/nginx/nginx.conf and a sample TLS certificate and private key in config/nginx/certs/overleaf_certificate.pem and config/nginx/certs/overleaf_key.pem respectively. If you already have a signed TLS certificate for use with Server Pro, replace the sample key and certificate with your key and certificate.

In order to run the proxy, change the value of the NGINX_ENABLED variable in config/overleaf.rc from false to true and re-run bin/up.

Further information about the TLS proxy can be found in the docs.

Consulting the Doctor

The Overleaf Toolkit comes with a handy tool for debugging your installation: bin/doctor

Let's run the bin/doctor script:

$ bin/doctor

We should see some output similar to this:

====== Overleaf Doctor ======
- Host Information
    - Linux
    ...
- Dependencies
    - bash
        - status: present
        - version info: 5.0.17(1)-release
    - docker
        - status: present
        - version info: Docker version 23.06.6, build 369ce74a3c
    - docker compose
        - status: present
        - version info: docker compose version v2.17.3
    ...
====== Configuration ======
    ...
====== Warnings ======
- None, all good
====== End ======

First, we see some information about the host system (the machine that the toolkit is being run on), then some information about dependencies. If any dependencies are missing, we will see a warning here. Next, the doctor checks our local configuration. At the end, the doctor will print out some warnings, if any problems were encountered.

When you run into problems with your toolkit, you should first run the doctor script and check it's output.

Getting Help

Users of the free Community Edition should open an issue on github.

Users of Server Pro should contact support@overleaf.com for assistance.

In both cases, it is a good idea to include the output of the bin/doctor script in your message.