Skip to content

INSTALL.md

Latest commit

 

History

History
193 lines (156 loc) · 7.71 KB

INSTALL.md

File metadata and controls

193 lines (156 loc) · 7.71 KB

Installing a Cocreate Server

These instructions on based on the more complicated installation instructions for Coauthor.

Test Server

Here is how to get a local test server running:

  1. Install Meteor: npm install -g meteor or sudo npm install -g meteor --unsafe-perm. Prefix with arch -x86_64 on Apple M1.
  2. Download Cocreate: git clone https://github.com/edemaine/cocreate.git
  3. Run meteor:
    • cd cocreate
    • meteor npm install
    • meteor

Even a test server will be accessible from the rest of the Internet, on port 3000.

Public Server

To deploy to a public server, we recommend deploying from a development machine via meteor-up. We provide two example deployment configurations:

Single Machine

We've found that one machine running everything (Meteor, MongoDB, Redis, proxy) to be reasonable for up to ~50 simultaneous users, given ~2-4GB of RAM and 1-2 cores. This configuration can be achieved fully automatically via mup as follows:

  1. Install Meteor and download Cocreate as above.
  2. Install mup and mup-redis via npm install -g mup mup-redis (after installing Node and thus NPM).
  3. Copy settings.json to .deploy1/settings.json and edit. In particular, you should change the cors-anywhere setting to point to your own CORS Anywhere server, or remove that setting altogether (to disable image loading via proxy). For further configuration choices for settings.json, see APM and CDN below.
  4. Edit .deploy1/mup.js to point to your hostname/IP and SSH key (for accessing the server), and maybe adjust RAM available to Meteor.
  5. cd .deploy1
  6. mup setup to install all necessary software on the server.
  7. mup deploy each time you want to deploy code to server (initially and after each git pull).

Multiple Machines (Scaling)

To scale beyond ~50 simultaneous users, we offer a different deployment configuration in the .deployN directory. It runs the following arrangement of servers:

Number Tasks Recommended configuration
several (currently 4) Meteor servers 2GB RAM (1GB causes occasional crashes), 1 core, open to UDP ingress/egress on port 123
one MongoDB server 4GB RAM, 4 cores
one Redis and proxy 1GB RAM, 1 core, open to TCP ingress ports 80 and 443

Cocreate assumes that all servers have roughly the same notion of time. So be sure to run an NTP client and open UDP port 123 for ingress and egress.

The nginx reverse proxy is the public facing web server (and should be the only server with publicly open ports), and automatically distributes requests to the Meteor servers (by IP hashing), automatically detecting crashed/upgrading servers and using the other servers to compensate. You should firewall the other servers (and the Redis server on the proxy machine) to protect them from outside access.

mup handles deployment of the Meteor servers and nginx reverse proxy. You need to manually setup the MongoDB and Redis servers.

As in the provided mup.js, all Meteor servers except one should have the COCREATE_SKIP_UPGRADE_DB environment variable set, to avoid multiple servers from upgrading the Cocreate database format from older versions.

Application Performance Management (APM)

To monitor server performance, you can use one of the following:

After creating an application on one of the servers above, edit your .deploy/settings.json to include the following (omit endpoint if you're using Monti):

{
  "kadira": {
    "appId": "xxxxxxxxxxxxxxxxx",
    "appSecret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "endpoint": "https://your-kadira-server:22022"
  }
}

MongoDB

All of Cocreate's data is stored in the Mongo database (which is part of Meteor). You probably want to do regular (e.g. daily) dump backups.

mup's MongoDB stores data in /var/lib/mongodb. MongoDB prefers an XFS filesystem, so you might want to create an XFS filesystem and mount or link it there. (For example, I have mounted an XFS volume at /data and linked via ln -s /data/mongodb /var/lib/mongodb).

mup also, by default, makes the MongoDB accessible to any user on the deployed machine. This is a security hole: make sure that there aren't any user accounts on the deployed machine. But it is also useful for manual database inspection and/or manipulation. Install MongoDB client tools, run mongo cocreate (or mongo then use cocreate) and you can directly query or update the collections. (Start with show collections, then e.g. db.messages.find().) On a test server, you can run meteor mongo to get the same interface.

CDN

Cocreate uses tex2svg-webworker to render LaTeX math. For sake of performance, we recommend serving this rather large WebWorker script via CDN, and the provided settings.json does so via JSDelivr. You can configure your .deploy/settings.json to use a different CDN as follows:

{
  "public": {
    "tex2svg": "https://your.cdn/tex2svg.js"
  }
}

Without this setting, e.g. when developing via meteor, the WebWorker script will be served from the Cocreate server.

CORS Anywhere Proxy

To enable flexible embedding images from the web, including those restricted by CORS, we recommend installing a CORS Anywhere proxy server and configuring Cocreate to use it by setting the cors-anywhere public setting in .deploy/settings.json. For example, here is how to use the CORS Anywhere public test server, which is rate limited and for development only:

{
  "public": {
    "cors-anywhere": "https://cors-anywhere.herokuapp.com/"
  }
}

CORS Anywhere is a framework for making proxy servers. A good specific server is Corsproxy which has easy-to-follow installation instructions (for ports ≥ 1024, e.g., 8080), along with the accompanying certbot letsencrypt installation instructions for SSL certificates. While it may be tempting to set REQUIRED_HEADER="Origin", Firefox won't send Origin headers for images so it's best to leave it empty.

If you omit the cors-anywhere setting, Cocreate will never attempt to proxy embedded images, so more images will fail to embed.

bcrypt on Windows

To install bcrypt on Windows (to avoid warnings about it missing), install windows-build-tools via npm install --global --production windows-build-tools, and then run meteor npm install bcrypt.