WIP: better docs

README.md

@@ -3,35 +3,32 @@
 (Note: this software is currently in beta testing. Functionality and documentation
 may be incomplete)
 
+This repository contains the Overleaf Toolkit, the standard tools for running a local
+instance of [Overleaf](https://overleaf.com). This toolkit will help you to set up and administer both Overleaf Community Edition (free to use, and community supported), and Overleaf Server Pro (commercial, with professional support).
+
 
 ## Getting Started
 
-See the [Quick Start Guide](./doc/quick-start-guide.md).
+Clone this repository locally:
+
+``` sh
+git clone https://github.com/overleaf/toolkit.git overleaf-toolkit
+```
+
+Then follow the [Quick Start Guide](./doc/quick-start-guide.md).
 
 
-## Dependencies
+## Documentation
 
-This project requires a modern unix system as a base (such as Ubuntu Linux).
-It also requires `bash`, `docker`, and `docker-compose`. 
-
-The `bin/doctor` script can be used to check for missing dependencies.
-
-Note: MacOS does not ship with a `realpath` program. In this case we fall
-back to a custom shell function to imitate some of what `realpath` does, but
-it is relatively limited. We recommend users on MacOS install the gnu coreutils
-with `brew install coreutils`, to get a working version of `realpath`.
+See [Documentation Index](./doc/index.md)
 
 
-## Doctor
+## Getting Help
 
-Run `bin/doctor` for debug output
+Users of the free Community Edition should [open an issue on github](https://github.com/overleaf/toolkit/issues). 
 
+Users of Server Pro should contact `support@overleaf.com` for assistance.
 
-## Docker Compose Wrappers
-
-The `bin/docker-compose` script is a wrapper around `docker-compose`, 
-and automatically loads the project configuration. `bin/up`, `bin/start`, etc,
-are convenience wrappers around `bin/docker-compose`.
 
 
 ## Config files

doc/_index.md

@@ -0,0 +1,23 @@
+# Documentation 
+
+
+Welcome to the documentation for the Overleaf Toolkit.
+
+
+## Getting Started
+
+- [Overview](./overview.md)
+- [Quick Start Guide](./quick-start-guide.md)
+- [Dependencies](./dependencies.md)
+
+
+## Using the Toolkit
+
+- The Doctor
+- Working with Docker-Compose Services
+
+
+## Configuration
+
+- [Configuration Overview](./configuration.md)
+- [overleaf.rc](./overleaf-rc.md)

doc/configuration.md

@@ -0,0 +1,43 @@
+# Configuration Overview
+
+This document describes the configuration files that are used to configure the Overleaf Toolkit.
+
+
+## Configuration File Location
+
+All user-owned configuration files are found in the `config/` directory.
+This directory is excluded from the git revision control system, so it will not be changed by updating the toolkit code. The toolkit will not change any data in the `config/` directory without your permission.
+
+
+## Initializing the Configuration
+
+Run `bin/init` to initialize a new configuration, with sensible defaults.
+This script will not over-write any existing configuration files.
+
+
+## Backing Up Your Configuration
+
+Use the `bin/backup-config` script to make a backup of your configuration files.
+For example: 
+
+```sh
+bin/backup-config -m zip ~/overleaf-config-backup.zip
+```
+
+
+## The `overleaf.rc` File
+
+The `config/overleaf.rc` file is the most important contains the most important "top level" configuration in the toolkit. It contains statements that set variables, in the format `VARIABLE_NAME=value`.
+
+
+See [The full specification](./overleaf-rc.md) for more details on the supported options. 
+
+
+## The `variables.env` File
+
+
+
+
+## The `version` File
+
+The `config/version` file contains the version number of the docker images that will be used to create the running instance of Overleaf.

doc/dependencies.md

@@ -0,0 +1,12 @@
+# Dependencies
+
+
+This project requires a modern unix system as a base (such as Ubuntu Linux).
+It also requires `bash`, `docker`, and `docker-compose`. 
+
+The `bin/doctor` script can be used to check for missing dependencies.
+
+Note: MacOS does not ship with a `realpath` program. In this case we fall
+back to a custom shell function to imitate some of what `realpath` does, but
+it is relatively limited. We recommend users on MacOS install the gnu coreutils
+with `brew install coreutils`, to get a working version of `realpath`.

doc/overleaf-rc.md

@@ -0,0 +1,100 @@
+# Configuration: `overleaf.rc`
+
+This document describes the variables that are supported in the `config/overleaf.rc` file.
+This file consists of variable definitions in the form `NAME=value`. Lines beginning with `#` are treated as comments.
+
+
+## Variables
+
+
+### `PROJECT_NAME`
+
+Sets the value of the `--project-name` flag supplied to `docker-compose`.
+This is useful when running multiple instances of Overleaf on one host, as each instance can have a different project name.
+
+- Default: overleaf
+
+
+### `SHARELATEX_DATA_PATH`
+
+Sets the path to the directory that will be mounted into the main `sharelatex` container, and used to store compile data. This can be either a full path (beginning with a `/`), or relative to the base directory of the toolkit.
+
+- Default: data/sharelatex
+
+
+### `SERVER_PRO`
+
+When set to `true`, tells the toolkit to use the Server Pro image (`quay.io/sharelatex/sharelatex-pro`), rather than the default Community Edition image (`sharelatex/sharelatex`). 
+
+- Default: false
+
+
+### `SIBLING_CONTAINERS_ENABLED`
+
+When set to `true`, tells the toolkit to use the "Sibling Containers" technique
+for compiling projects in separate sandboxes, using a separate docker container for
+each project. See (the legacy documentation on Sandboxed Compiles)[https://github.com/sharelatex/sharelatex/wiki/Server-Pro:-sandboxed-compiles] for more information.
+
+Requires `SERVER_PRO=true`
+
+- Default: false
+
+
+### `DOCKER_SOCKET_PATH`
+
+Sets the path to the docker socket on the host machine (the machine running the toolkit code). When `SIBLING_CONTAINERS_ENABLED` is `true`, the socket will be mounted into the container, to allow the compiler service to spawn new docker containers on the host.
+
+Requires `SIBLING_CONTAINERS_ENABLED=true`
+
+- Default: /var/run/docker.sock
+
+
+### `MONGO_ENABLED`
+
+When set to `true`, tells the toolkit to create a MongoDB container, to host the database.
+When set to `false`, this container will not be created, and the system will use the MongoDB database specified by `MONGO_URL` instead.
+
+- Default: true
+
+
+### `MONGO_URL`
+
+Specifies the MongoDB connection URL to use when `MONGO_ENABLED` is `false`
+
+- Default: not set
+
+
+### `MONGO_DATA_PATH`
+
+Sets the path to the directory that will be mounted into the `mongo` container, and used to store the MongoDB database. This can be either a full path (beginning with a `/`), or relative to the base directory of the toolkit. This option only affects the local `mongo` container that is created when `MONGO_ENABLED` is `true`.
+
+- Default: data/mongo
+
+
+### `REDIS_ENABLED`
+
+When set to `true`, tells the toolkit to create a Redis container, to host the redis database.
+When set to `false`, this container will not be created, and the system will use the  Redis database specified by `REDIS_HOST` and `REDIS_PORT` instead.
+
+- Default: true
+
+
+### `REDIS_HOST`
+
+Specifies the Redis host to use when `REDIS_ENABLED` is `false`
+
+- Default: not set
+
+
+### `REDIS_PORT`
+
+Specifies the Redis port to use when `REDIS_ENABLED` is `false`
+
+- Default: not set
+
+
+### `REDIS_DATA_PATH`
+
+Sets the path to the directory that will be mounted into the `redis` container, and used to store the Redis database. This can be either a full path (beginning with a `/`), or relative to the base directory of the toolkit. This option only affects the local `redis` container that is created when `REDIS_ENABLED` is `true`.
+
+- Default: data/redis

doc/overview.md

@@ -0,0 +1,31 @@
+# Overleaf Toolkit Overview
+
+
+## What is Overleaf?
+
+
+
+
+
+## What is the Overleaf Toolkit?
+
+
+
+
+
+## Project Structure
+
+
+
+
+## Docker, Docker-Compose, and Overleaf
+
+
+
+
+## The `bin/` directory
+
+
+
+
+##