overleaf/services/git-bridge/README.md

139 lines
4.4 KiB
Markdown
Raw Normal View History

# writelatex-git-bridge
## Docker
The `Dockerfile` contains all the requirements for building and running the
writelatex-git-bridge.
```bash
# build the image
docker build -t writelatex-git-bridge .
# run it with the demo config
docker run -v `pwd`/conf/local.json:/conf/runtime.json writelatex-git-bridge
```
## Native install
### Required packages
2014-11-03 08:19:49 -05:00
2016-09-12 09:26:56 -04:00
* `maven` (for building, running tests and packaging)
* `jdk-8` (for compiling and running)
2014-11-03 11:26:51 -05:00
### Commands
2016-09-12 09:26:56 -04:00
To be run from the base directory:
**Build jar**:
`mvn package`
**Run tests**:
`mvn test`
**Clean**:
`mvn clean`
To be run from the dev-environment:
**Build jar**:
`bin/run git-bridge make package`
**Run tests**:
`bin/run git-bridge make test`
**Clean**:
`bin/run git-bridge make clean`
### Installation
2014-11-03 11:26:51 -05:00
Install dependencies:
2014-11-03 11:26:51 -05:00
```
sudo apt-get update
sudo apt-get install -y maven
sudo apt-get install -y openjdk-8-jdk
sudo update-alternatives --set java /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java
sudo update-alternatives --set javac /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/javac
```
2014-12-05 21:03:43 -05:00
Create a config file according to the format below.
2015-01-10 07:55:57 -05:00
2015-01-09 02:21:13 -05:00
Run `mvn package` to build, test, and package it into a jar at `target/writelatex-git-bridge-1.0-SNAPSHOT-jar-with-dependencies.jar`.
2014-11-03 11:26:51 -05:00
2014-12-05 20:56:07 -05:00
Use `java -jar <path_to_jar> <path_to_config_file>` to run the server.
2014-12-05 20:50:35 -05:00
## Runtime Configuration
2014-12-05 20:50:35 -05:00
The configuration file is in `.json` format.
2014-12-05 20:50:35 -05:00
{
2014-12-05 21:01:47 -05:00
"port" (int): the port number,
2016-08-24 20:06:17 -04:00
"rootGitDirectory" (string): the directory in which to store
git repos and the db/atts,
2014-12-05 21:01:47 -05:00
"apiBaseUrl" (string): base url for the snapshot api,
"username" (string, optional): username for http basic auth,
"password" (string, optional): password for http basic auth,
"postbackBaseUrl" (string): the postback url,
2016-08-24 20:06:17 -04:00
"serviceName" (string): current name of writeLaTeX
in case it ever changes,
"oauth2" (object): { null or missing if oauth2 shouldn't be used
2016-08-24 19:58:44 -04:00
"oauth2ClientID" (string): oauth2 client ID,
"oauth2ClientSecret" (string): oauth2 client secret,
2016-08-24 20:06:17 -04:00
"oauth2Server" (string): oauth2 server,
with protocol and
without trailing slash
2016-08-24 19:58:44 -04:00
},
2017-08-03 18:46:04 -04:00
"repoStore" (object, optional): { configure the repo store
"maxFileSize" (long, optional): maximum size of a file, inclusive
},
2016-08-24 20:06:17 -04:00
"swapStore" (object, optional): { the place to swap projects to.
if null, type defaults to
"noop"
2016-08-24 19:58:44 -04:00
"type" (string): "s3", "memory", "noop" (not recommended),
"awsAccessKey" (string, optional): only for s3,
"awsSecret" (string, optional): only for s3,
"s3BucketName" (string, optional): only for s3
},
2016-08-24 20:06:17 -04:00
"swapJob" (object, optional): { configure the project
swapping job.
if null, defaults to no-op
"minProjects" (int64): lower bound on number of projects
present. The swap job will never go
below this, regardless of what the
watermark shows. Regardless, if
minProjects prevents an eviction,
the swap job will WARN,
"lowGiB" (int32): the low watermark for swapping,
i.e. swap until disk usage is below this,
"highGiB" (int32): the high watermark for swapping,
i.e. start swapping when
disk usage becomes this,
"intervalMillis" (int64): amount of time in between running
swap job and checking watermarks.
3600000 is 1 hour
2015-10-25 09:58:40 -04:00
}
2014-12-05 20:50:35 -05:00
}
You have to restart the server for configuration changes to take effect.
2018-10-25 09:56:42 -04:00
## Creating OAuth app
2019-11-12 10:16:54 -05:00
In dev-env, run the following command in mongo to create the oauth application
for git-bridge.
```
db.oauthApplications.insert({
"clientSecret" : "v1.G5HHTXfxsJMmfFhSar9QhJLg/u4KpGpYOdPGwoKdZXk=",
2019-11-12 10:16:54 -05:00
"grants" : [
"password"
],
"id" : "264c723c925c13590880751f861f13084934030c13b4452901e73bdfab226edc",
"name" : "Overleaf Git Bridge",
"redirectUris" : [],
"scopes" : [
"git_bridge"
]
})
2018-10-25 09:56:42 -04:00
```