README.md 6.65 KB
Newer Older
1 2
Ethertoff
=========
3

eric's avatar
eric committed
4 5 6 7 8 9
![](http://osp.kitchen/api/osp.tools.ethertoff/raw/iceberg/ethertoff-write-read-print.gif)

Ethertoff is a simple collaborative web platform, much resembling a wiki but featuring
realtime editing thanks to Etherpad. Its output is constructed with equal love for print
and web.

10 11 12 13 14 15
> Just a question: I thought it was ethertopff and not ethertoff but I don't
> remember why. What is the actual name?
>
> Well someone misspelled ethertopdf as ethertopf which sounds like römertopf
> and than somebody else understood ethertoff like chokotoff and chokotoff
> being Bruxellois I thought it might be the best of all these references
OSP's avatar
OSP committed
16

17 18

Ethertoff has been initially developed for the OSP 2013 Summerschool bearing the name ‘Relearn’.
OSP's avatar
OSP committed
19 20 21

<http://relearn.be/>

22
Ethertoff is structured as a wiki where each page constitutes an Etherpad.
23

24
The pad is available to logged in users (‘write-mode’).
25 26
The text of the pad is available to everyone (‘read-mode’).

27
Ethertoff is a shell for an Etherpad installation hosted on the same domain.
28 29 30 31 32 33 34
This integration is based on Sofian Benaissa’s bridge between Django and Etherpad,
originally created for THINK WE MUST/CON-VOCATION a performance during Promiscuous
Infrastructures entrelacées, an exhibition by the collective Artivistic at SKOL.

-  <https://github.com/sfyn/django-etherpad-lite>
-  <http://www.riotnrrd.info/tech/etherpad-lite-performances-ongoing-saga>
-  <http://www.thinkwemust.org/?page_id=6>
35 36 37 38 39

- - -

## Installation instructions

40
Requires Django 2.0
41
First create and install a virtual environment [1]. Then:
gijs's avatar
gijs committed
42

svilayphiou's avatar
svilayphiou committed
43
    sudo aptitude install python-dev libxml2-dev libxslt-dev libz-dev
44 45
    pip install "django<2.1" django-markdown python-dateutil rdflib 
    # old pip install html5tidy pytz six isodate lxml
46
    pip install https://github.com/devjones/PyEtherpadLite/archive/master.zip
stdin's avatar
stdin committed
47
    pip install https://github.com/aleray/markdown-figures/archive/master.zip
48 49 50

    mkdir -p ~/src/
    cd ~/src
gijs's avatar
gijs committed
51
    git clone http://gitlab.constantvzw.org/osp/tools.ethertoff.git
gijs's avatar
gijs committed
52
    cd tools.ethertoff      # [2]
53
    cd ethertoff
eric's avatar
eric committed
54
    cp local_settings.py.example local_settings.py
55
    # Change database details in local_settings.py
eric's avatar
eric committed
56
    cd ..
57 58
    # python manage.py syncdb
    python manage.py migrate 
59

60 61 62 63 64 65 66
Change the info of your domain name and website name in the Sites section on
<http://localhost:8000/admin>. **Do not add "http://" in your domain name,
otherwise the Re-index function won't work.**

### If you have the error "Site matching query does not exist"

Open the python shell
67 68 69

    python manage.py shell

70
And then do the following (replace the "domain" and "name" with your own info):
71 72 73 74

    from django.contrib.sites.models import Site
    site = Site.objects.create(domain='example.com', name='example.com')
    site.save()
75
    
76 77 78


## Install Etherpad-lite
79 80 81 82 83
    
    mkdir -p ~/src
    cd ~/src
    git clone https://github.com/ether/etherpad-lite.git
    
84
## --> install node js
svilayphiou's avatar
svilayphiou committed
85 86 87 88
Install Make:

    sudo aptitude install build-essentials

89
Linux Binaries (.tar.gz) from http://nodejs.org/download/
ludi's avatar
ludi committed
90

91 92 93 94


## Launch Etherpad-lite

95
run Etherpad with:
96 97 98
    
    ~/src/etherpad-lite/bin/run.sh
    
99
Your Etherpad is running at http://127.0.0.1:9001/
100
    
svilayphiou's avatar
merge  
svilayphiou committed
101
In Etherpad’s folder, you will find a file called APIKEY.txt
102
you need its contents later 
103 104 105 106 107



## Launch Ethertoff

108
Run the server:
109
    python manage.py runserver
110 111 112 113 114

visit the admin at: http://127.0.0.1:800/admin/
you can login with the superuser you created when you synced the database
Now, on the Django admin:

115
    Etherpadlite > Servers > Add
116 117 118 119
        # if local
        url: http://127.0.0.1:9001/
        # if on a server
        url: http://domainname/ether/
120
        api_key: the contents of the file APIKEY.txt in Etherpad files
121 122 123 124

Go back to the admin home, and then add a new group:
    Auth > Groups > Add
    
125
Go back to the admin home, and then add the superuser (and all needed users) to the group you just created
126 127 128 129
    Auth > Users

Go back to the admin home, and then create an Etherpad Group based upon the group and the server you just created.
    Etherpadlite > Groups > Add
130
    
131
Now Ethertoff is served at http://127.0.0.1:8000/ locally, or on your domain name on a server.
132

133
You can set the site name, that appears on the header, in the ‘sites’ app in the admin.
134 135 136

- - -

137
[^1]: Something like:
138 139 140

    mkdir -p ~/venvs/
    cd ~/venvs/
141 142
    virtualenv ethertoff
    source ~/venvs/ethertoff/bin/activate
143 144 145

- - -

146
# Extra challenge! Installing on a server.
147 148 149 150 151 152 153

Some extra challenges. Basically we can split it up like:

example.com /        -> django
            /ether/  -> etherpad
            /static/ -> django static files

154 155 156
To test if everything is working, you can use screen to run gunicorn and Etherpad scripts at the same time, and then use a daemon like Supervisor to run them in the background.


157 158 159

## MYSQL

160 161 162
    # pip install "distribute>0.6.24"
    sudo aptitude install libmysqlclient-dev python-dev
    pip install MySQL-python mysqlclient
163 164 165


## DJANGO
166 167 168 169 170 171 172 173 174
The django application runs through mod_wsgi (Apache) or gunicorn
(nginx), or whatever way you prefer to run your wsgi python apps.
You map it to the root of your domain.

For django, we need to set up some folder where the static files
are collected. You do this with the command: `python manage.py collectstatic`
This folder we then serve through nginx or apache, and map to the
folder /static/.

175 176 177 178
    sudo aptitude install nginx
    pip install gunicorn
    cd /etc/nginx/sites-available/
    # (edit nginx config file)
179
    sudo vim ethertoff.conf
180
    cd ../sites-enabled/
181 182
    sudo ln -s ../sites-available/ethertoff
    cd ethertoff_directory/
183 184 185 186 187 188 189 190 191
    # (edit gunicorn config file)
    vim run.sh 
    chmod +x run.sh
    sudo service nginx start
    # Run the server
    ./run.sh

To run the server in the background, use Supervisor daemon.

192 193


194
## ETHERPAD
195 196 197 198 199 200
Etherpad, finally, runs as its own server. You probably need to use
a supervisor such as supervisord to make sure it keeps running.
You will also need to set up a database, because its default database
is not intended for use on servers. Finally, you will need to reverse
proxy the Etherpad process from your main web server, mapping it to
a folder such as /ether/.
201

202 203


204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
## SUPERVISOR
To run django and etherpad in the background.

    sudo aptitude install supervisor
    # Edit specific config file for each application in /etc/supervisor/conf.d/
    # Example of config file:

    [program:pads]
    directory = /absolute/path/to/etherpad-lite/bin/
    user = username
    command = /absolute/path/to/etherpad-lite/bin/run.sh
    stopwaitsecs=60

    stdout_logfile = /absolute/path/to/etherpad-lite/logfile.log
    stderr_logfile = /absolute/path/to/etherpad-lite/logfile.log

    # Then run the apps daemon
    supervisord
    supervisorctl start app_name