Repository files navigation

PeerDoc is a collaborative real-time rich-text editor with undo/redo, cursor tracking, inline comments,permissions/sharing control over documents, a change history. Things you would expect from a moderncollaborative editor on the web.

But the main difference is that it provides two types of collaboration:

• real-time collaboration between collaborators on the draft of the document
• fork and merge request style of collaboration with others, allowing collaboration to scale beyond a small group of collaborators

For more information about PeerDoc, what it can do and how it works, seethis blog post.

PeerDoc is a stable prototype. It has been already used in production. All features described above are implemented,but some of them are implemented in its basic form. For example, authentication and registration is currently very simple.Merge requests just show a diff but do not offer discussion. Or decision making to approve merge requests.You cannot add attachments to documents. And so on. Seeissuesfor more details.

PeerDoc is distributed as aDocker image. To get the latest stable version,useregistry.gitlab.com/peer/doc/branch/main:latest.

The Docker image is based ontozd/meteor Docker image sosee theremore details how to run and configure the image.

PeerDoc can be configured usingsettings.json file. Seeexample settings file.

• tokenSharedSecret: PeerDoc can be embedded and can acceptuser query string parameter with a token about the user currentlysigned in into the parent app. Thatuser token is encrypted and signed usingtokenSharedSecret. Used also for authentication of calls to the API.
• appCivistIntegration: An object withendpoint,email, andpassword fields. Used when embedded insideAppcivistto notify Appcivist when documents are updated or comments made.
• apiControlled: When set totrue, then creation of documents, forking, merging, etc., can be doneonly through the API and not through the webinterface. Useful when PeerDoc is embedded and the parent app controls the collaboration process.
• passwordlessAuthDisabled: By default, PeerDoc comes with simple password less authentication (anyone can just pick an username). Probably you want todisable that in production.
• mergingForkingOfAllDocuments: By default, PeerDoc allows forking only published documents (and merging back). (Published documents are those whichyou cannot edit anymore in real-time.) But you can enable that all documents (including those which are still being edited in real-time) can be forkedand merged back to. Depends on what type of collaborative process you want.
• defaultLanguage: Default language of the user interface to use, if user does not have its preferred language set.
• defaultPermissions: Default permissions to give to new users. By default new users can create documents and view and create comments (but firstthey have to have access to a documents to comment).

PeerDoc can be embedded in an iframe. You should provide the following query string parameters in the URL you are embedding:

• embed: Set it totrue to ask PeerDoc to not render toolbar and padding around the main area of the app (it is assumed that the parent app provides those).
• user: Provide a JSON-encoded, AES-128-GCM encrypted and signed, base64 encoded token with information about the user. It is not a JWT but a custom token. If user does not yet exist, it is created by PeerDoc internally.JSON has the following fields:avatar,username,id,email, andlanguage.

When being embedded (embed is set totrue) PeerDoc useswindow.parent.postMessage to send a{size: {width, height}} messages to the parent appwith the size of the embedded content. This allows the parent app to resizeiframe accordingly.

PeerDoc can be controlled through an API. Authentication is done using theuser query string parameter which should containuser token as described for embedding. Available endpoints:

• POST/document: Creates a new document. On success returns a JSON with{status: "success", documentId, path}. On error returns a JSON with{status: "error"}.
• POST/document/export/<document id>: Exports a document to HTML. On success returns a JSON with{status: "success", html}. On error returns a JSON with{status: "error"}.
• POST/document/publish/<document id>: Publishes the document. On success returns a JSON with{status: "success"}. On error returns a JSON with{status: "error"}.
• POST/document/share/<document id>: Configures permissions/sharing control of the document. Accepts a JSON with{visibility, token_users: {admin, edit}}.visibility can betrue orfalse, corresponding to public and private visibility levels.admin andedit are lists of user tokens for which corresponding permission should be set. All other permissions are removed. On success returns a JSON with{status: "success"}. On error returns a JSON with{status: "error"}.
• POST/document/fork/<document id>: Forks the document. On success returns a JSON with{status: "success", documentId, path}. On error returns a JSON with{status: "error"}.
• POST/document/merge/<document id>: Merges the document. On success returns a JSON with{status: "success"}. On error returns a JSON with{status: "error"}.

The application usesMeteor web framework. Install it:

$ curl https://install.meteor.com/| sh

Clone the repositoryrecursively:

$ git clone --recursive https://gitlab.com/peer/doc.git

Install dependencies:

$ meteor npm install

Add and configure settings:

$ cp settings.example.json settings.json

Run it:

$ meteor --settings settings.json

And openhttp://localhost:3000/.

• Meteor
• JavaScript
• SCSS
• Vue +Vuetify
• ProseMirror

Seecode style guide for more information.

To run a linting tool to check the code style, run:

$ meteor npm run lint

The translations are handled by thevue-gettext package.

To generate translations:

1. Runmeteor npm run extract-strings to extract user-visible strings.
2. Go totranslations/locale and find the.po file associated with the language you want to translate.
3. Update the.po file with translations for extracted strings.
4. Generate an updated translations JSON file by runningmeteor npm run translations.

$ meteor npm run test-watch

This will watch for any code changes and rerun unit tests. Test results for both server-sideand client-side are provided in the terminal.

If you want to run unit tests only once, run:

$ meteor npm run test

If you prefer to see client-side test results in a browser, run:

$ meteor npm run test-watch-browser

And openhttp://localhost:3100/ (note a different port).

Run in one terminal:

$ meteor npm run test-app

This will run the full app in test mode onhttp://localhost:3000/,but you do not have to open it. Run in another terminal:

$ meteor npm run cypress

This will openCypress runner which we use for acceptance tests.You can select tests to run or run all of them and you will see how they are run intesting browser, and be able to inspect results. It will watch for any changes andrerun tests, too.

If you want to run acceptance tests only once, and see results in the terminal, run:

$ meteor npm run cypress-run

During CI testing acceptance tests are run as well. Results are recorded and availableinCypress Dashboard.Moreover, results are also submitted for visual diffing and are availableinPercy.

You can find links to a particular Cypress recording and Percy build for a CI run inGitLab CI's run output.