search

kentonv / etherpad-lite

Really real-time collaborative document editing for the rest of us
http://etherpad.org
Apache License 2.0
30 stars 11 forks source link

readme

Etherpad on Sandstorm

This branch ports Etherpad to Sandstorm. To use it:

  1. Run bin/installDeps.sh once after cloning the repo. Note that in the main branch, this is done automatically by run.sh, but in the Sandstorm branch that line has been removed because it doesn't make sense inside the sandbox.
  2. Run bin/run.sh once, let Etherpad start, and then ctrl+C it. This does some first-time setup, creating some necessary files. If you do not do this, you'll get EROFS errors when Etherpad tries to create these files inside the sandbox.
  3. You may now run spk dev as described in the Sandstorm porting guide.
  4. If you plan to run spk pack to build a final package, FIRST run bin/run.sh again. This time, actually open up the local Etherpad instance, click on things, and especially open the timeslider. During this time, Etherpad is populating the minified code cache, which will be shipped with the package. This improves Etherpad startup time. HOWEVER, if you plan to do any further Etherpad development touching client-side code, you must first delete the cache. Otherwise, spk dev will happily serve the cached files and you won't see your changes.
  5. Also, before spk pack, optionally run minify-cache.sh to minify all assets. This requires uglify and cleancss commands are on your PATH.

Original Etherpad README follows

A really-real time collaborative word processor for the web

alt text

About

Etherpad is a really-real time collaborative editor maintained by the Etherpad Community.

Etherpad is written in JavaScript (99.9%) on both the server and client so it's easy for developers to maintain and add new features. Because of this Etherpad has tons of customizations that you can leverage.

Etherpad is designed to be easily embeddable and provides a HTTP API that allows your web application to manage pads, users and groups. It is recommended to use the available client implementations in order to interact with this API.

There is also a jQuery plugin that helps you to embed Pads into your website.

There's also a full-featured plugin framework, allowing you to easily add your own features. By default your Etherpad is rather sparse and because Etherpad takes a lot of it's inspiration from Wordpress plugins are really easy to install and update. Once you have Etherpad installed you should visit the plugin page and take control.

Finally, Etherpad comes with translations into most languages! Users are automatically delivered the correct language for their local settings.

Visit beta.etherpad.org to test it live.

Also, check out the FAQ, really!

Installation

Etherpad works with node v0.10+ (except 6.0 and 6.1).

Windows

Prebuilt windows package

This package works out of the box on any windows machine, but it's not very useful for developing purposes...

  1. Download the latest windows package
  2. Extract the folder

Now, run start.bat and open http://localhost:9001 in your browser. You like it? Next steps.

Fancy install

You'll need node.js and (optionally, though recommended) git.

  1. Grab the source, either
  2. start bin\installOnWindows.bat

Now, run start.bat and open http://localhost:9001 in your browser.

Update to the latest version with git pull origin, then run bin\installOnWindows.bat, again.

If cloning to a subdirectory within another project, you may need to do the following:

  1. Start the server manually (e.g. node/node_modules/ep_etherpad-lite/node/server.js])
  2. Edit the db filename in settings.json to the relative directory with the file (e.g. application/lib/etherpad-lite/var/dirty.db)
  3. Add auto-generated files to the main project .gitignore

Next steps.

GNU/Linux and other UNIX-like systems

You'll need gzip, git, curl, libssl develop libraries, python and gcc.

Additionally, you'll need node.js installed, Ideally the latest stable version, we recommend installing/compiling nodejs from source (avoiding apt).

As any user (we recommend creating a separate user called etherpad):

  1. Move to a folder where you want to install Etherpad. Clone the git repository git clone git://github.com/ether/etherpad-lite.git
  2. Change into the new directory containing the cloned source code cd etherpad-lite

Now, run bin/run.sh and open http://127.0.0.1:9001 in your browser.

Update to the latest version with git pull origin. The next start with bin/run.sh will update the dependencies.

You like it? Next steps.

Next Steps

Tweak the settings

You can initially modify the settings in settings.json. (If you need to handle multiple settings files, you can pass the path to a settings file to bin/run.sh using the -s|--settings option. This allows you to run multiple Etherpad instances from the same installation.) Once you have access to your /admin section settings can be modified through the web browser.

You should use a dedicated database such as "mysql", if you are planning on using etherpad-in a production environment, since the "dirtyDB" database driver is only for testing and/or development purposes.

Plugins and themes

Etherpad is very customizable through plugins. Instructions for installing themes and plugins can be found in the plugin wiki article.

Helpful resources

The wiki is your one-stop resource for Tutorials and How-to's, really check it out! Also, feel free to improve these wiki pages.

Documentation can be found in docs/.

Development

Things you should know

Understand git and watch this video on getting started with Etherpad Development.

If you're new to node.js, start with Ryan Dahl's Introduction to Node.js.

You can debug Etherpad using bin/debugRun.sh.

If you want to find out how Etherpad's Easysync works (the library that makes it really realtime), start with this PDF (complex, but worth reading).

Getting started

You know all this and just want to know how you can help?

Look at the TODO list and our Issue tracker. (Please consider using jshint, if you plan to contribute code.)

Also, and most importantly, read our Developer Guidelines, really!

Get in touch

Join the mailinglist and make some noise on our busy freenode irc channel #etherpad-lite-dev!

Modules created for this project

Donate!

License

Apache License v2