etherpad-lite/README.md

126 lines
6.9 KiB
Markdown
Raw Normal View History

# A really-real time collaborative word processor for the web
2013-04-04 02:56:36 +02:00
![alt text](http://i.imgur.com/zYrGkg3.gif "Etherpad in action on PrimaryPad")
2011-08-21 18:23:04 +02:00
2011-04-07 16:17:40 +02:00
# About
2013-04-04 02:20:46 +02:00
Etherpad is a really-real time collaborative editor maintained by the Etherpad Community.
2013-04-04 02:22:46 +02:00
2013-04-04 02:20:46 +02:00
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.
2013-04-04 02:22:46 +02:00
2013-04-04 02:20:46 +02:00
Etherpad is designed to be easily embeddable and provides a [HTTP API](https://github.com/ether/etherpad-lite/wiki/HTTP-API)
2013-04-04 02:24:09 +02:00
that allows your web application to manage pads, users and groups. It is recommended to use the [available client implementations](https://github.com/ether/etherpad-lite/wiki/HTTP-API-client-libraries) in order to interact with this API.
There is also a [jQuery plugin](https://github.com/ether/etherpad-lite-jquery-plugin) that helps you to embed Pads into your website.
2014-12-03 17:43:15 +01:00
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.
2013-04-04 02:24:09 +02:00
2013-04-04 02:20:46 +02:00
Finally, Etherpad comes with translations into most languages! Users are automatically delivered the correct language for their local settings.
2012-09-10 14:44:06 +02:00
**Visit [beta.etherpad.org](http://beta.etherpad.org) to test it live.**
2012-09-10 14:44:06 +02:00
2012-11-14 20:26:37 +01:00
Also, check out the **[FAQ](https://github.com/ether/etherpad-lite/wiki/FAQ)**, really!
2011-04-07 15:35:13 +02:00
# Installation
Etherpad works with node v0.10+ and io.js.
2013-04-01 14:07:38 +02:00
2011-08-21 18:23:04 +02:00
## Windows
2012-09-10 14:44:06 +02:00
### 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](http://etherpad.org/#download)
2012-09-10 14:44:06 +02:00
2. Extract the folder
Now, run `start.bat` and open <http://localhost:9001> in your browser. You like it? [Next steps](#next-steps).
### Fancy install
You'll need [node.js](http://nodejs.org) and (optionally, though recommended) git.
1. Grab the source, either
2012-11-14 20:05:58 +01:00
- download <https://github.com/ether/etherpad-lite/zipball/master>
- or `git clone https://github.com/ether/etherpad-lite.git` (for this you need git, obviously)
2012-09-10 14:44:06 +02:00
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`
2012-09-10 14:44:06 +02:00
[Next steps](#next-steps).
2013-04-04 19:23:56 +02:00
## GNU/Linux and other UNIX-like systems
2012-09-10 14:44:06 +02:00
You'll need gzip, git, curl, libssl develop libraries, python and gcc.
- *For Debian/Ubuntu*: `apt-get install gzip git curl python libssl-dev pkg-config build-essential`
- *For Fedora/CentOS*: `yum install gzip git curl python openssl-devel && yum groupinstall "Development Tools"`
- *For FreeBSD*: `portinstall node, npm, git (optional)`
2014-11-01 13:36:57 +01:00
Additionally, you'll need [node.js](http://nodejs.org) installed, Ideally the latest stable version, we recommend installing/compiling nodejs from source (avoiding apt).
2011-08-02 23:15:59 +02:00
2013-08-23 00:32:25 +02:00
**As any user (we recommend creating a separate user called etherpad):**
2011-08-02 23:15:59 +02:00
2013-08-23 00:32:25 +02:00
1. Move to a folder where you want to install Etherpad. Clone the git repository `git clone git://github.com/ether/etherpad-lite.git`
2012-09-10 14:44:06 +02:00
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.
2012-09-10 14:44:06 +02:00
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).
2011-04-07 15:35:13 +02:00
2012-09-10 14:44:06 +02:00
# Next Steps
2011-04-07 16:17:40 +02:00
2012-09-10 14:44:06 +02:00
## Tweak the settings
2013-04-04 02:20:46 +02:00
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.
2013-04-04 02:20:46 +02:00
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](https://github.com/ether/etherpad-lite/wiki/Available-Plugins).
2012-09-10 14:44:06 +02:00
## Helpful resources
2012-11-14 20:05:58 +01:00
The [wiki](https://github.com/ether/etherpad-lite/wiki) is your one-stop resource for Tutorials and How-to's, really check it out! Also, feel free to improve these wiki pages.
2011-06-02 13:29:09 +02:00
2012-09-10 14:44:06 +02:00
Documentation can be found in `docs/`.
2011-08-04 21:33:39 +02:00
2012-09-10 14:44:06 +02:00
# Development
2011-06-02 13:29:09 +02:00
2012-09-10 14:44:06 +02:00
## Things you should know
2015-04-15 12:52:03 +02:00
Understand [git](https://training.github.com/) and watch this [video on getting started with Etherpad Development](http://youtu.be/67-Q26YH97E).
2011-07-11 22:45:19 +02:00
2012-09-10 14:44:06 +02:00
If you're new to node.js, start with Ryan Dahl's [Introduction to Node.js](http://youtu.be/jo_B4LTHi3I).
2011-06-02 13:29:09 +02:00
2013-04-04 02:20:46 +02:00
You can debug Etherpad using `bin/debugRun.sh`.
2011-06-02 13:29:09 +02:00
2012-11-14 20:26:37 +01:00
If you want to find out how Etherpad's `Easysync` works (the library that makes it really realtime), start with this [PDF](https://github.com/ether/etherpad-lite/raw/master/doc/easysync/easysync-full-description.pdf) (complex, but worth reading).
2011-08-02 23:15:59 +02:00
2012-09-10 14:44:06 +02:00
## Getting started
You know all this and just want to know how you can help?
2011-06-02 13:29:09 +02:00
2012-11-14 20:05:58 +01:00
Look at the [TODO list](https://github.com/ether/etherpad-lite/wiki/TODO) and our [Issue tracker](https://github.com/ether/etherpad-lite/issues). (Please consider using [jshint](http://www.jshint.com/about/), if you plan to contribute code.)
2011-06-02 13:29:09 +02:00
2013-02-20 21:38:24 +01:00
Also, and most importantly, read our [**Developer Guidelines**](https://github.com/ether/etherpad-lite/blob/master/CONTRIBUTING.md), really!
2011-08-01 20:24:11 +02:00
2012-09-10 14:44:06 +02:00
# Get in touch
2013-04-04 02:20:46 +02:00
Join the [mailinglist](http://groups.google.com/group/etherpad-lite-dev) and make some noise on our busy freenode irc channel [#etherpad-lite-dev](http://webchat.freenode.net?channels=#etherpad-lite-dev)!
2011-12-21 21:32:17 +01:00
2011-08-01 20:24:11 +02:00
# Modules created for this project
2013-01-15 22:16:19 +01:00
* [ueberDB](https://github.com/Pita/ueberDB) "transforms every database into a object key value store" - manages all database access
* [channels](https://github.com/Pita/channels) "Event channels in node.js" - ensures that ueberDB operations are atomic and in series for each key
* [async-stacktrace](https://github.com/Pita/async-stacktrace) "Improves node.js stacktraces and makes it easier to handle errors"
2011-08-01 20:24:11 +02:00
2012-09-10 14:44:06 +02:00
# Donate!
* [Flattr] (http://flattr.com/thing/71378/Etherpad-Foundation)
* Paypal - Press the donate button on [etherpad.org](http://etherpad.org)
2013-02-13 21:14:15 +01:00
* [Bitcoin] (https://coinbase.com/checkouts/1e572bf8a82e4663499f7f1f66c2d15a)
2012-02-26 15:20:50 +01:00
2012-02-26 15:22:32 +01:00
# License
2012-11-14 20:26:37 +01:00
[Apache License v2](http://www.apache.org/licenses/LICENSE-2.0.html)