{"id":13992076,"url":"https://github.com/overleaf/clsi","last_synced_at":"2025-07-22T15:31:04.895Z","repository":{"id":14071955,"uuid":"16775434","full_name":"overleaf/clsi","owner":"overleaf","description":"A web api for compiling LaTeX documents in the cloud","archived":true,"fork":false,"pushed_at":"2021-12-16T16:35:03.000Z","size":4436,"stargazers_count":198,"open_issues_count":0,"forks_count":56,"subscribers_count":36,"default_branch":"master","last_synced_at":"2024-11-29T12:38:14.797Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/overleaf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-02-12T17:29:04.000Z","updated_at":"2024-11-16T20:32:48.000Z","dependencies_parsed_at":"2022-09-23T18:50:31.428Z","dependency_job_id":null,"html_url":"https://github.com/overleaf/clsi","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/overleaf/clsi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overleaf%2Fclsi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overleaf%2Fclsi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overleaf%2Fclsi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overleaf%2Fclsi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/overleaf","download_url":"https://codeload.github.com/overleaf/clsi/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/overleaf%2Fclsi/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266520616,"owners_count":23942301,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-22T02:00:09.085Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-09T14:01:46.668Z","updated_at":"2025-07-22T15:31:04.397Z","avatar_url":"https://github.com/overleaf.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"⚠️ This repository has been migrated into [`overleaf/overleaf`](https://github.com/overleaf/overleaf). See the [monorepo announcement](https://github.com/overleaf/overleaf/issues/923) for more info. ⚠️\n\n---\n\noverleaf/clsi\n===============\n\nA web api for compiling LaTeX documents in the cloud\n\nThe Common LaTeX Service Interface (CLSI) provides a RESTful interface to traditional LaTeX tools (or, more generally, any command line tool for composing marked-up documents into a display format such as PDF or HTML). The CLSI listens on the following ports by default:\n\n* TCP/3013 - the RESTful interface\n* TCP/3048 - reports load information\n* TCP/3049 - HTTP interface to control the CLSI service\n\nThese defaults can be modified in `config/settings.defaults.js`.\n\nThe provided `Dockerfile` builds a Docker image which has the Docker command line tools installed. The configuration in `docker-compose-config.yml` mounts the Docker socket, in order that the CLSI container can talk to the Docker host it is running in. This allows it to spin up `sibling containers` running an image with a TeX distribution installed to perform the actual compiles.\n\nThe CLSI can be configured through the following environment variables:\n\n* `ALLOWED_COMPILE_GROUPS` - Space separated list of allowed compile groups\n* `ALLOWED_IMAGES` - Space separated list of allowed Docker TeX Live images\n* `CATCH_ERRORS` - Set to `true` to log uncaught exceptions\n* `COMPILE_GROUP_DOCKER_CONFIGS` - JSON string of Docker configs for compile groups\n* `COMPILES_HOST_DIR` - Working directory for LaTeX compiles\n* `COMPILE_SIZE_LIMIT` - Sets the body-parser [limit](https://github.com/expressjs/body-parser#limit)\n* `DOCKER_RUNNER` - Set to true to use sibling containers\n* `DOCKER_RUNTIME` -\n* `FILESTORE_DOMAIN_OVERRIDE` - The url for the filestore service e.g.`http://$FILESTORE_HOST:3009`\n* `FILESTORE_PARALLEL_FILE_DOWNLOADS` - Number of parallel file downloads\n* `FILESTORE_PARALLEL_SQL_QUERY_LIMIT` - Number of parallel SQL queries\n* `LISTEN_ADDRESS` - The address for the RESTful service to listen on. Set to `0.0.0.0` to listen on all network interfaces\n* `PROCESS_LIFE_SPAN_LIMIT_MS` - Process life span limit in milliseconds\n* `SENTRY_DSN` - Sentry [Data Source Name](https://docs.sentry.io/product/sentry-basics/dsn-explainer/)\n* `SMOKE_TEST` - Whether to run smoke tests\n* `SQLITE_PATH` - Path to SQLite database\n* `SYNCTEX_BIN_HOST_PATH` - Path to SyncTeX binary\n* `TEXLIVE_IMAGE` - The TeX Live Docker image to use for sibling containers, e.g. `gcr.io/overleaf-ops/texlive-full:2017.1`\n* `TEX_LIVE_IMAGE_NAME_OVERRIDE` - The name of the registry for the Docker image e.g. `gcr.io/overleaf-ops`\n* `TEXLIVE_IMAGE_USER` - When using sibling containers, the user to run as in the TeX Live image. Defaults to `tex`\n* `TEXLIVE_OPENOUT_ANY` - Sets the `openout_any` environment variable for TeX Live (see the `\\openout` primitive [documentation](http://tug.org/texinfohtml/web2c.html#tex-invocation))\n\nFurther environment variables configure the [metrics module](https://github.com/overleaf/metrics-module)\n\nInstallation\n------------\n\nThe CLSI can be installed and set up as part of the entire [Overleaf stack](https://github.com/overleaf/overleaf) (complete with front end editor and document storage), or it can be run as a standalone service. To run is as a standalone service, first checkout this repository:\n\n    $ git clone git@github.com:overleaf/clsi.git\n\nThen build the Docker image:\n\n    $ docker build . -t overleaf/clsi\n\nThen pull the TeX Live image:\n\n    $ docker pull texlive/texlive\n\nThen start the Docker container:\n\n    $ docker run --rm \\\n        -p 127.0.0.1:3013:3013 \\\n        -e LISTEN_ADDRESS=0.0.0.0 \\\n        -e DOCKER_RUNNER=true \\\n        -e TEXLIVE_IMAGE=texlive/texlive \\\n        -e TEXLIVE_IMAGE_USER=root \\\n        -e COMPILES_HOST_DIR=\"$PWD/compiles\" \\\n        -v \"$PWD/compiles:/app/compiles\" \\\n        -v \"$PWD/cache:/app/cache\" \\\n        -v /var/run/docker.sock:/var/run/docker.sock \\\n        --name clsi \\\n        overleaf/clsi\n\nNote: if you're running the CLSI in macOS you may need to use `-v /var/run/docker.sock.raw:/var/run/docker.sock` instead.\n\nThe CLSI should then be running at \u003chttp://localhost:3013\u003e\n\nImportant note for Linux users\n==============================\n\nThe Node application runs as user `node` in the CLSI, which has uid `1000`. As a consequence of this, the `compiles` folder gets created on your host with `uid` and `gid` set to `1000`.\n```\nls -lnd compiles\ndrwxr-xr-x 2 1000 1000 4096 Mar 19 12:41 compiles\n```\n\nIf there is a user/group on your host which also happens to have `uid` / `gid` `1000` then that user/group will have ownership of the compiles folder on your host.\n\nLaTeX runs in the sibling containers as the user specified in the `TEXLIVE_IMAGE_USER` environment variable. In the example above this is set to `root`, which has uid `0`. This creates a problem with the above permissions, as the root user does not have permission to write to subfolders of `compiles`.\n\nA quick fix is to give the `root` group ownership and read write permissions to `compiles`, with `setgid` set so that new subfolders also inherit this ownership:\n```\nsudo chown -R 1000:root compiles\nsudo chmod -R g+w compiles\nsudo chmod g+s compiles\n```\nAnother solution is to create a `sharelatex` group and add both `root` and the user with `uid` `1000` to it. If the host does not have a user with that `uid`, you will need to create one first.\n```\nsudo useradd --uid 1000 host-node-user # If required\nsudo groupadd sharelatex\nsudo usermod -a -G sharelatex root\nsudo usermod -a -G sharelatex $(id -nu 1000)\nsudo chown -R 1000:sharelatex compiles\nsudo chmod -R g+w compiles\nsudo chmod g+s compiles\n```\n\nThis is a facet of the way docker works on Linux. See this [upstream issue](https://github.com/moby/moby/issues/7198)\n\n\nConfig\n------\n\nThe CLSI will use a SQLite database by default, but you can optionally set up a MySQL database and then fill in the database name, username and password in the config file at `config/settings.development.js`.\n\nAPI\n---\n\nThe CLSI is based on a JSON API.\n\n#### Example Request\n\n(Note that valid JSON should not contain any comments like the example below).\n\n    POST /project/\u003cproject-id\u003e/compile\n\n```json5\n{\n    \"compile\": {\n        \"options\": {\n            // Which compiler to use. Can be latex, pdflatex, xelatex or lualatex\n            \"compiler\": \"lualatex\",\n            // How many seconds to wait before killing the process. Default is 60.\n            \"timeout\": 40\n        },\n        // The main file to run LaTeX on\n        \"rootResourcePath\": \"main.tex\",\n        // An array of files to include in the compilation. May have either the content\n        // passed directly, or a URL where it can be downloaded.\n        \"resources\": [\n          {\n            \"path\": \"main.tex\",\n            \"content\": \"\\\\documentclass{article}\\n\\\\begin{document}\\nHello World\\n\\\\end{document}\"\n          }\n          // ,{\n          //     \"path\": \"image.png\",\n          //     \"url\": \"www.example.com/image.png\",\n          //     \"modified\": 123456789 // Unix time since epoch\n          // }\n        ]\n    }\n}\n```\n\nWith `curl`, if you place the above JSON in a file called `data.json`, the request would look like this:\n\n``` shell\n$ curl -X POST -H 'Content-Type: application/json' -d @data.json http://localhost:3013/project/\u003cid\u003e/compile\n```\n\nYou can specify any project-id in the URL, and the files and LaTeX environment will be persisted between requests.\nURLs will be downloaded and cached until provided with a more recent modified date.\n\n#### Example Response\n\n```json\n{\n    \"compile\": {\n        \"status\": \"success\",\n        \"outputFiles\": [{\n            \"type\": \"pdf\",\n            \"url\": \"http://localhost:3013/project/\u003cproject-id\u003e/output/output.pdf\"\n        }, {\n            \"type\": \"log\",\n            \"url\": \"http://localhost:3013/project/\u003cproject-id\u003e/output/output.log\"\n        }]\n    }\n}\n```\n\nLicense\n-------\n\nThe code in this repository is released under the GNU AFFERO GENERAL PUBLIC LICENSE, version 3. A copy can be found in the `LICENSE` file.\n\nCopyright (c) Overleaf, 2014-2021.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foverleaf%2Fclsi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foverleaf%2Fclsi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foverleaf%2Fclsi/lists"}